ai-consultants 4.0.0 → 4.0.2

package/.env.example

@@ -188,6 +188,10 @@ QWEN3_CMD=qwen
 # is installed; the xAI API is selected when the CLI is unavailable and a key
 # exists. A failed CLI launch also falls back to the API at runtime.
 # GROK_USE_API=false
+# Grok OAuth concurrency: shared keeps one runner-owned credential generation
+# so parallel consultants can safely reuse refresh rotation. serialized holds
+# the adapter lock for the full CLI call and is intended for diagnostics.
+# GROK_OAUTH_MODE=shared
 
 # =============================================================================
 # API-ONLY AND FALLBACK CONFIGURATION
@@ -205,6 +209,7 @@ GROK_CMD=grok
 GROK_MODEL=grok-4.6
 GROK_TIMEOUT=180
 GROK_MAX_TURNS=4
+GROK_OAUTH_MODE=shared
 GROK_API_MAX_TOKENS=4096
 GROK_API_URL=https://api.x.ai/v1/chat/completions
 # GROK_REASONING_EFFORT= # max_quality sets xhigh (Grok Build maximum)

package/CLAUDE.md

@@ -6,7 +6,7 @@ AI Consultants is a multi-model coverage system that queries up to 10 AI consult
 
 **Self-Exclusion**: The invoking agent is automatically excluded from both the panel and synthesis. Claude Code won't query or synthesize with Claude, Codex CLI won't query or synthesize with Codex, etc.
 
-**Version**: 4.0.0
+**Version**: 4.0.2
 
 ## Distribution
 
@@ -760,6 +760,26 @@ curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/s
 
 ## Changelog
 
+### v4.0.2
+
+- **The Grok adapter used to copy a rotating OAuth credential into a disposable HOME and delete any refreshed token at exit.** Parallel calls amplified the race: both could seed from one refresh token, one rotation vanished with its temp directory, and the ambient session could be left stale. `scripts/lib/grok_oauth.sh` now owns a durable generation under the XDG data root and `scripts/query_grok.sh` defaults to `GROK_OAUTH_MODE=shared`.
+- **Shared means credential state only.** Every invocation still has a private HOME, workspace, prompt file, output, capability-probe HOME, permission mode, strict sandbox, empty tool surface, model, and effort. Concurrent processes use one runner-owned `GROK_HOME`, allowing Grok Build's native auth lock to coordinate refresh while inference remains outside the ai-consultants lock.
+- **Publication is optimistic and atomic.** A recoverable directory lock bounds seed, bootstrap, inventory, and publication; valid rotation is staged mode 600 and renamed into the ambient `auth.json`. The marker binds generation and last-synced SHA-256. If a concurrent external `grok login` changes the ambient digest, that login wins, the consultation fails temporarily, and no API fallback occurs.
+- **Malformed and obsolete state fails closed but recovers forward.** Corrupt credentials never replace ambient auth; dead locks are reclaimed; unpersistible refreshes publish no answer. A later run reseeds from valid ambient state. Generations carrying the exact legacy runner-owned `config.toml` signature are superseded without modification or deletion.
+- **Grok 1.0.4 required exact-transport fixes beyond the reference implementation.** Its pristine-home bootstrap lazily creates metadata/cache/DB state; capability probes must use a separate credential-free HOME; authenticated inventory is bounded and coordinated. Provider-owned `config.toml` cannot be replaced before each inventory, and the display sentence “You are logged in with grok.com.” is not stable enough to be an auth gate. Exit 0, a still-valid credential, and the requested inventory model are the attestation.
+- **Secrets remain private.** The prompt and tokens never enter argv. Grok dispatch uses redacted `run_query` errors, so token-shaped provider stderr is absent from stdout, normal logs, error envelopes, and artifacts. Forced API mode remains stateless; missing/auth-unavailable CLI fallback and post-dispatch fallback suppression are unchanged.
+- **Verification closes both concurrency layers.** The adapter suite grows to 88 checks and covers simultaneous fake dispatch, rotation/reuse, external-login CAS, corrupt state, dead locks, atomic policy reconciliation, legacy migration, stateless API mode, serialized mode, and token leakage. A real two-process `grok-4.6`/`xhigh` smoke returned structured `PONG` twice with exit 0, no workspace changes, no API fallback, and fully aligned ambient/generation/marker state. Full gate: 23/23 suites, 452/452 core checks, ShellCheck and PR #14 CI green.
+
+  Deliberate residuals: superseded generations are retained because deleting one that an active process still references would be unsafe. Real forced refresh rotation and a real concurrent `grok login` were not induced; those conflict paths are verified with controlled fakes. The separate local 4.1.0 model-default WIP is not part of this release.
+
+### v4.0.1
+
+- **The installer's first line of user-visible output was six major/minor generations stale.** `scripts/install.sh:53` printed `AI Consultants v2.10 - Installation` even while the public binary, package metadata, npm registry, active checkout, and doctor all reported v4.0.0. That did not change installed bytes or runtime behavior, but it made a successful v4 install look wrong at the exact moment users were deciding whether to trust it.
+- **The banner is now deliberately version-neutral, not dynamically coupled to a tenth version surface.** The curl-piped installer prints before it has cloned or updated the checkout, so sourcing `scripts/config.sh` there would either be impossible on a fresh install or would report the old local version during an update. A static `AI Consultants - Installation` label stays truthful throughout both paths and does not need another release-time rewrite.
+- **The failure is regression-tested through rendered output.** `scripts/test_install.sh` sources the existing define-only path, calls `print_header`, requires the installer label, and rejects `AI Consultants v<major>.<minor>` in the banner. The focused installer suite grows to 47 checks; the full 23-suite gate and ShellCheck pass on the 4.0.1 surfaces.
+
+  Deliberately unchanged: no runtime, model, preset, credential, host command, or minisite copy changes. The showcase site already reflects the ten-consultant v4 panel; after npm serves 4.0.1 it needs only its two mechanical version surfaces bumped.
+
 ### v4.0.0
 
 - **`max_quality` now means the full ten-consultant panel at each exact transport's strongest supported effort and response budget.** GLM and DeepSeek run at `max`; Grok uses its highest supported setting. K3-256k, MiniMax M3, and Qwen3.8-Max remain confined to the maximum tier, with Qwen promoted only when the authenticated Token Plan transport is already configured.

package/README.md

@@ -1,8 +1,8 @@
-# AI Consultants v4.0.0
+# AI Consultants v4.0.2
 
 > **Coverage, not a single guess.** A panel of up to 10 frontier models from different vendors fans out on your question in parallel and hands you the *union* of what they collectively see — the risks, edge cases, and approaches a single model misses.
 
-[![Version](https://img.shields.io/badge/version-4.0.0-blue.svg)](https://github.com/matteoscurati/ai-consultants)
+[![Version](https://img.shields.io/badge/version-4.0.2-blue.svg)](https://github.com/matteoscurati/ai-consultants)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-orange.svg)](https://docs.anthropic.com/en/docs/claude-code/skills)
 [![GitHub stars](https://img.shields.io/github/stars/matteoscurati/ai-consultants?style=social)](https://github.com/matteoscurati/ai-consultants)
@@ -389,7 +389,16 @@ Grok uses Grok Build with `grok-4.6` in an isolated, tool-free sandbox. Prompts
 are passed through a private file rather than process arguments. It falls back
 to the xAI API only when the CLI is missing, cannot launch, or has no usable
 authentication and `GROK_API_KEY` is configured; post-launch request failures
-are surfaced without a silent API charge. Qwen3 and MiniMax can also switch
+are surfaced without a silent API charge. Grok CLI OAuth defaults to concurrent
+`shared` mode: HOME, workspace, prompt, output, permissions, and agent state
+remain isolated per invocation, while processes share one runner-owned
+persistent `GROK_HOME` so the CLI's own auth lock can coordinate refresh.
+Credential adoption/publication uses a short lock and digest CAS, so an
+external `grok login` wins and the affected run fails without overwriting it or
+falling back to the API. Set `GROK_OAUTH_MODE=serialized` only for diagnostic
+full-run serialization. A new generation performs one locked inventory
+bootstrap because Grok 1.0.4 lazily initializes home metadata; inference is
+never serialized by that bootstrap. Qwen3 and MiniMax can also switch
 from their CLI to API transport. Gemini, Codex, Claude, and Mistral are
 CLI/API switchable. Gemini, Grok, and Kimi verify the requested model
 against the CLI inventory before dispatch when that inventory exists. Grok and

package/SKILL.md

@@ -5,10 +5,10 @@ license: MIT
 compatibility: Requires bash, jq, and at least 2 AI CLI tools (agy, codex, vibe, etc.). macOS and Linux.
 metadata:
   author: matteoscurati
-  version: 4.0.0
+  version: 4.0.2
 ---
 
-# AI Consultants v4.0.0 - AI Expert Panel
+# AI Consultants v4.0.2 - AI Expert Panel
 
 **Coverage, not a single guess.** Convene a panel of AI "consultants" from different vendors for coding questions: they fan out in parallel and you get the *union* of what they collectively see — the risks, edge cases, and approaches a single model misses. Each consultant has a **configurable persona** that decorrelates its analysis.
 
@@ -88,6 +88,14 @@ Configuration (presets, strategies, features, personas, API keys) can be managed
 
 **CLI/API Mode**: Gemini, Codex, Claude, Mistral, Qwen, Grok, and MiniMax can switch between CLI and API mode via `*_USE_API` environment variables. Grok is CLI-first on Grok Build with `grok-4.6` and falls back to the xAI API when the CLI cannot run. Gemini auto-selects API mode when `GEMINI_API_KEY` is set (no `agy` install needed) and the CLI otherwise. Mistral keeps separate API (`MISTRAL_MODEL`) and Vibe (`MISTRAL_CLI_MODEL`) identifiers.
 
+Grok CLI OAuth defaults to `GROK_OAUTH_MODE=shared`: concurrent invocations
+share one runner-owned persistent `GROK_HOME` so the vendor auth lock can
+coordinate refresh, while HOME, workspace, prompt, output, permissions, and
+agent state remain isolated per invocation. A short adapter lock publishes a
+valid rotated credential atomically; an external `grok login` wins the CAS and
+makes the affected run fail without API fallback. `serialized` remains an
+explicit diagnostic mode. Forced API mode stays stateless.
+
 Grok and Kimi are compatible by capability rather than by CLI version. Before
 dispatch, their adapters verify the required headless arguments, requested
 model, and structured-output surface. Compatible version changes are accepted;

package/docs/COST_RATES.md

@@ -1,4 +1,4 @@
-# Cost Rates - AI Consultants v4.0.0
+# Cost Rates - AI Consultants v4.0.2
 
 This page documents the per-token rates used by the cost tracking system.
 

package/docs/SETUP.md

@@ -396,6 +396,17 @@ INVOKING_AGENT=codex ./scripts/consult_all.sh "Question"
 
 Seven consultants can switch between CLI mode (using local CLI tools) and API mode (direct API calls): **Gemini, Codex, Claude, Mistral, Qwen3, Grok, and MiniMax**. Grok is CLI-first and runs in an isolated, tool-free strict sandbox. It falls back automatically only when Grok Build is missing, cannot launch, or lacks usable authentication and a key is available; request failures after launch are surfaced without an API fallback.
 
+Grok's normal OAuth mode is `GROK_OAUTH_MODE=shared`, which is safe for the
+parallel panel: each call gets a private HOME/workspace/prompt/output, while a
+runner-owned persistent `GROK_HOME` lets Grok Build coordinate token refresh
+with its own lock. A short ai-consultants lock atomically seeds and publishes
+valid generations; a concurrent external `grok login` wins the CAS and makes
+the affected run fail without an API fallback. Use
+`GROK_OAUTH_MODE=serialized` only as a diagnostic fallback. Forced API mode is
+stateless and does not read or create the shared OAuth generation. A newly
+created shared generation runs one locked inventory bootstrap to let Grok 1.0.4
+initialize its home metadata; the lock is released before inference.
+
 ### Why Use API Mode?
 
 - **No CLI installation required**: Use API keys without installing CLI tools

package/docs/cost_rates.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.0.0",
+  "version": "4.0.2",
   "updated": "2026-08-23",
   "models": {
     "_comment_units": "All rates are USD per 1,000 tokens (per-1K). lib/costs.sh computes cost as (token_count / 1000) * rate, so every value here MUST be a per-1K rate = (provider $/1M price) / 1000. Do NOT paste $/MTok figures directly.",

package/docs/releases/v4.0.1.md

@@ -0,0 +1,57 @@
+# Release v4.0.1
+
+**Date:** 2026-08-24
+
+**Type:** Patch — truthful installer presentation
+
+**Previous:** v4.0.0
+
+## Highlights
+
+- The installer no longer displays the obsolete label `AI Consultants v2.10` while installing a 4.x package.
+- The banner is intentionally version-neutral, preventing the same drift in future releases.
+- A hermetic regression test renders the banner and rejects hardcoded package versions.
+
+## What's New
+
+### A truthful installer banner
+
+The curl and git-clone installation paths previously began with a hardcoded `AI Consultants v2.10 - Installation` banner. The installed package, public binary, and runtime were correctly at v4.0.0, but the stale presentation made a successful installation look inconsistent.
+
+The banner now reads simply `AI Consultants - Installation`. This is more reliable than loading the package version dynamically: on a fresh curl-piped install there is no checkout to read yet, while on an update the checkout still contains the old version when the banner is printed.
+
+### Regression coverage
+
+The installer suite now checks the rendered header itself. It requires the version-neutral installer label and fails if a package-style SemVer is hardcoded into that banner again.
+
+## Breaking Changes
+
+None. Installation behavior, files, commands, configuration, credentials, model selection, and runtime output are unchanged.
+
+## Upgrade Guide
+
+```bash
+# npx, after npm publishes 4.0.1
+npx ai-consultants version
+
+# active git-clone installation
+cd ~/.claude/skills/ai-consultants && git pull
+```
+
+No configuration or authentication migration is required.
+
+## Verification
+
+- Installer-focused suite: 47/47 checks
+- Full local gate: 23/23 suites
+- ShellCheck: passed
+- Installer banner rendered directly from the shipped helper: passed
+- Showcase site audit: ten consultant cards, no Cursor consultant card, correct v4 preset counts, ready for the mechanical 4.0.1 sync after npm publication
+
+## Commits
+
+- Release commit added at publication time
+
+## Contributors
+
+- @matteoscurati

package/docs/releases/v4.0.2.md

@@ -0,0 +1,98 @@
+# Release v4.0.2
+
+**Date:** 2026-08-28
+
+**Type:** Patch — concurrency-safe Grok OAuth
+
+**Previous:** v4.0.1
+
+## Highlights
+
+- Parallel Grok Build consultations can now share rotating OAuth safely without sharing agent state.
+- Refreshed credentials survive temporary HOME cleanup and are published atomically to the ambient session.
+- A concurrent external `grok login` always wins; the affected consultation fails without overwriting it or creating an API charge.
+- A real two-process `grok-4.6` smoke returned two structured `PONG` responses with exit 0.
+
+## What's New
+
+### Shared OAuth by default
+
+`GROK_OAUTH_MODE=shared` is now the normal Grok CLI path. The runner maintains one persistent credential generation under:
+
+```text
+$XDG_DATA_HOME/ai-consultants/grok-shared-oauth
+```
+
+Only `GROK_HOME` is shared. Each consultation still receives an independent HOME, workspace, private prompt, output, capability-probe environment, strict sandbox, empty tool surface, model, and effort.
+
+Grok Build's own auth lock coordinates token refresh between concurrent processes. The ai-consultants lock is used only for bounded seed, first-use bootstrap, authenticated inventory, and publication — never for inference.
+
+### Atomic refresh publication and CAS
+
+The shared marker binds the active generation to the SHA-256 of the credential last synchronized with ambient `~/.grok/auth.json`.
+
+After a run:
+
+- unchanged valid credentials require no write;
+- a valid rotation is copied into a mode-600 candidate and atomically renamed;
+- malformed rotation fails closed;
+- a changed ambient digest means an external login won, so the run fails temporarily and publishes no successful answer;
+- a publication failure never triggers the separately billed xAI API fallback.
+
+`GROK_OAUTH_MODE=serialized` remains available for diagnostic comparison and holds the runner lock across the complete CLI call.
+
+### Provider-owned configuration
+
+Grok 1.0.4 lazily creates provider-required metadata, caches, DBs, and `config.toml`. ai-consultants therefore preserves that file and stores its own atomic contract in `.ai-consultants-policy.json`. The effective agent restrictions remain pinned through the invocation arguments.
+
+Generations produced by the earlier development runner are recognized from their exact legacy config signature and superseded without deletion or mutation.
+
+### Sanitized failures
+
+Grok requests use redacted retry logging. Token-shaped provider stderr remains only in ephemeral private storage and never reaches argv, stdout, logs, error envelopes, or consultation artifacts.
+
+## Breaking Changes
+
+None. `shared` replaces the unsafe disposable-copy behavior for CLI OAuth, but model, effort, permissions, sandbox, response schema, API transport, and fallback classification remain unchanged.
+
+Users who need full-run serialization for diagnosis can set:
+
+```bash
+GROK_OAUTH_MODE=serialized
+```
+
+## Upgrade Guide
+
+```bash
+# npx, after npm publishes 4.0.2
+npx ai-consultants@4.0.2 version
+
+# active git-clone installation
+cd ~/.claude/skills/ai-consultants && git pull
+```
+
+No login or configuration migration is required. The first shared run seeds from the existing ambient Grok credential. No API key is copied or created.
+
+## Verification
+
+- Grok adapter: 88/88 checks
+- Configurator: 91/91 checks
+- Core gate: 452/452 checks
+- Full local gate: 23/23 suites
+- ShellCheck, JSON validation, npm tarball, and `git diff --check`: passed
+- PR #14 CI on exact head `883fad7`: passed
+- Real concurrent smoke: two exit-0 structured `PONG` responses, CLI transport, `grok-4.6`, `xhigh`, no workspace/runtime/lock residue, no API fallback, valid and hash-aligned ambient/generation/marker state
+
+## Provider-Specific Residuals
+
+- Real token rotation during concurrent inference was not forced; rotation/reuse is verified synthetically.
+- A real concurrent external `grok login` was not induced; external-login precedence is verified synthetically.
+- Superseded generations are retained to avoid deleting state still referenced by an active process.
+
+## Commits
+
+- `6c9e4b2` Merge pull request #14
+
+## Contributors
+
+- @matteoscurati

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-consultants",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "A cross-vendor panel of up to 10 AI models that returns the coverage union of their distinct perspectives",
   "bin": {
     "ai-consultants": "bin/ai-consultants"

package/references/configuration.md

@@ -259,6 +259,7 @@ GROK_MODEL=grok-4.6
 GROK_MAX_TURNS=4
 GROK_API_MAX_TOKENS=4096
 GROK_REASONING_EFFORT=      # max_quality sets xhigh (Grok Build maximum)
+GROK_OAUTH_MODE=shared      # shared (parallel default) | serialized (diagnostic)
 DEEPSEEK_MODEL=deepseek-v4-pro
 DEEPSEEK_API_MAX_TOKENS=16384
 DEEPSEEK_MAX_QUALITY_TIMEOUT=600
@@ -285,6 +286,28 @@ Set `GROK_USE_API=true` only to force the API path. The adapter accepts any CLI
 version that exposes the complete required headless interface and requested
 model; `metadata.cli_version` is provenance, not a version pin.
 
+`GROK_OAUTH_MODE=shared` is the normal CLI path because ai-consultants launches
+consultants in parallel. Each Grok invocation keeps a private HOME, workspace,
+prompt, output, permissions, and tool-free agent policy. Concurrent Grok
+processes share only a runner-owned persistent `GROK_HOME` generation under
+`$XDG_DATA_HOME/ai-consultants/grok-shared-oauth` (or the standard XDG data
+fallback). Grok Build's own auth lock coordinates refreshes inside that shared
+generation; a short ai-consultants lock protects seeding, adoption, atomic
+runner-policy reconciliation, and atomic publication back to the ambient
+`~/.grok/auth.json`. An external `grok login` always wins the digest-based CAS:
+the affected consultation fails temporarily and never overwrites the new login
+or falls back to a separately billed API request. Malformed credentials and
+unpersisted refreshes fail closed. Use `GROK_OAUTH_MODE=serialized` only to hold
+the adapter lock across the complete CLI run for diagnostic comparison. Forced
+API mode is stateless and never creates or reads the shared OAuth generation.
+Each new generation also performs exactly one model-inventory bootstrap under
+the short lock because Grok 1.0.4 lazily initializes home metadata; all later
+inventory probes and every inference remain concurrent.
+Grok 1.0.4 retains ownership of its generated `config.toml`; ai-consultants does
+not replace provider-required sections. Instead it atomically reconciles a
+separate `.ai-consultants-policy.json`, while the actual enforced surface stays
+pinned by the per-invocation CLI arguments.
+
 `max_quality` sets `GROK_REASONING_EFFORT=xhigh` (the highest value accepted by
 Grok Build),
 `GLM_REASONING_EFFORT=max`, and `DEEPSEEK_REASONING_EFFORT=max`. Grok passes

package/scripts/config.sh

@@ -202,6 +202,7 @@ GROK_MODEL="${GROK_MODEL:-grok-4.6}"
 GROK_TIMEOUT_SECONDS="${GROK_TIMEOUT:-180}"
 GROK_API_MAX_TOKENS="${GROK_API_MAX_TOKENS:-4096}"
 GROK_MAX_TURNS="${GROK_MAX_TURNS:-4}"
+GROK_OAUTH_MODE="${GROK_OAUTH_MODE:-shared}"
 GROK_API_URL="${GROK_API_URL:-https://api.x.ai/v1/chat/completions}"
 GROK_FORMAT="${GROK_FORMAT:-openai}"
 # Grok Build's official credential name is XAI_API_KEY. Keep the historical
@@ -221,7 +222,7 @@ if [[ -z "${GROK_USE_API+x}" ]]; then
         GROK_USE_API=false
     fi
 fi
-export GROK_USE_API
+export GROK_USE_API GROK_OAUTH_MODE
 
 # =============================================================================
 # DEEPSEEK CONFIGURATION - The Methodologist (API-based)
@@ -1010,4 +1011,4 @@ EOF
 # VERSION
 # =============================================================================
 
-AI_CONSULTANTS_VERSION="4.0.0"
+AI_CONSULTANTS_VERSION="4.0.2"

package/scripts/install.sh

@@ -50,7 +50,7 @@ fi
 print_header() {
     echo ""
     echo -e "${BLUE}+---------------------------------------------------------------+${NC}"
-    echo -e "${BLUE}|           AI Consultants v2.10 - Installation                 |${NC}"
+    echo -e "${BLUE}|              AI Consultants - Installation                    |${NC}"
     echo -e "${BLUE}+---------------------------------------------------------------+${NC}"
     echo ""
 }

package/scripts/lib/common.sh

@@ -221,7 +221,9 @@ run_query() {
 
         # Error handling
         local error_msg=""
-        [[ -f "$error_file" ]] && error_msg=$(head -5 "$error_file" 2>/dev/null)
+        if [[ "${RUN_QUERY_REDACT_ERRORS:-false}" != "true" && -f "$error_file" ]]; then
+            error_msg=$(head -5 "$error_file" 2>/dev/null)
+        fi
 
         # First line of the CLI's own stderr — the actual reason (auth error,
         # command not found, etc.). Kept for the final failure message so it

package/scripts/lib/grok_oauth.sh

@@ -0,0 +1,455 @@
+#!/bin/bash
+# grok_oauth.sh - Persistent, concurrency-safe Grok Build OAuth handoff.
+#
+# Shared mode keeps one runner-owned credential generation across invocations.
+# Each invocation still receives its own HOME, workspace, prompt, and output;
+# only GROK_HOME is shared so Grok Build's own auth.json.lock can coordinate a
+# refresh. A short adapter lock protects generation adoption and publication.
+# Serialized mode retains a per-run GROK_HOME and holds that adapter lock for
+# the full CLI sequence as a diagnostic fallback.
+
+GROK_OAUTH_SOURCE_HOME=""
+GROK_OAUTH_SHARED_ROOT=""
+GROK_OAUTH_ACTIVE_HOME=""
+GROK_OAUTH_GENERATION=""
+GROK_OAUTH_BASELINE_HASH=""
+GROK_OAUTH_LOCK_PATH=""
+GROK_OAUTH_LOCK_HELD=0
+GROK_OAUTH_SYNC_STATUS="not_attempted"
+GROK_OAUTH_ERROR=""
+GROK_OAUTH_LOCK_WAIT_SECONDS=25
+GROK_OAUTH_BOOTSTRAP_TIMEOUT_SECONDS=20
+
+grok_oauth_digest() {
+    if command -v shasum >/dev/null 2>&1; then
+        shasum -a 256 "$1" 2>/dev/null | awk '{print $1}'
+    elif command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "$1" 2>/dev/null | awk '{print $1}'
+    else
+        return 1
+    fi
+}
+
+grok_oauth_credential_valid() {
+    local credential="$1"
+    [[ -f "$credential" && ! -L "$credential" ]] || return 1
+    jq -e '
+        type == "object" and
+        ([.[]? | objects |
+          select(((.key // "") | type == "string" and length > 0) and
+                 ((.refresh_token // "") | type == "string" and length > 0))] |
+         length > 0)
+    ' "$credential" >/dev/null 2>&1
+}
+
+grok_oauth_release_lock() {
+    local owner_pid=""
+    [[ "$GROK_OAUTH_LOCK_HELD" -eq 1 ]] || return 0
+    if [[ -d "$GROK_OAUTH_LOCK_PATH" && ! -L "$GROK_OAUTH_LOCK_PATH" &&
+          -f "$GROK_OAUTH_LOCK_PATH/owner" && ! -L "$GROK_OAUTH_LOCK_PATH/owner" ]]; then
+        owner_pid=$(<"$GROK_OAUTH_LOCK_PATH/owner")
+        if [[ "$owner_pid" == "$$" ]]; then
+            rm -f -- "$GROK_OAUTH_LOCK_PATH/owner"
+            rmdir "$GROK_OAUTH_LOCK_PATH" >/dev/null 2>&1 || true
+        fi
+    fi
+    GROK_OAUTH_LOCK_HELD=0
+}
+
+grok_oauth_acquire_lock() {
+    local owner_pid=""
+    [[ -d "$GROK_OAUTH_SOURCE_HOME" && ! -L "$GROK_OAUTH_SOURCE_HOME" ]] || return 1
+    GROK_OAUTH_LOCK_PATH="$GROK_OAUTH_SOURCE_HOME/.ai-consultants-oauth.lock.d"
+    [[ ! -L "$GROK_OAUTH_LOCK_PATH" ]] || return 1
+
+    if ! mkdir "$GROK_OAUTH_LOCK_PATH" 2>/dev/null; then
+        if [[ -f "$GROK_OAUTH_LOCK_PATH/owner" && ! -L "$GROK_OAUTH_LOCK_PATH/owner" ]]; then
+            owner_pid=$(<"$GROK_OAUTH_LOCK_PATH/owner")
+        fi
+        if [[ "$owner_pid" =~ ^[1-9][0-9]*$ ]] && ! kill -0 "$owner_pid" 2>/dev/null; then
+            rm -f -- "$GROK_OAUTH_LOCK_PATH/owner"
+            rmdir "$GROK_OAUTH_LOCK_PATH" >/dev/null 2>&1 || return 2
+            mkdir "$GROK_OAUTH_LOCK_PATH" 2>/dev/null || return 2
+        else
+            return 2
+        fi
+    fi
+
+    if ! printf '%s\n' "$$" > "$GROK_OAUTH_LOCK_PATH/owner" ||
+       ! chmod 700 "$GROK_OAUTH_LOCK_PATH" ||
+       ! chmod 600 "$GROK_OAUTH_LOCK_PATH/owner"; then
+        rm -f -- "$GROK_OAUTH_LOCK_PATH/owner"
+        rmdir "$GROK_OAUTH_LOCK_PATH" >/dev/null 2>&1 || true
+        return 1
+    fi
+    GROK_OAUTH_LOCK_HELD=1
+}
+
+grok_oauth_acquire_lock_wait() {
+    local deadline rc
+    deadline=$(( $(date +%s) + GROK_OAUTH_LOCK_WAIT_SECONDS ))
+    while :; do
+        rc=0
+        grok_oauth_acquire_lock || rc=$?
+        [[ "$rc" -eq 2 ]] || return "$rc"
+        [[ "$(date +%s)" -lt "$deadline" ]] || return 2
+        sleep 1
+    done
+}
+
+grok_oauth_write_controlled_config() {
+    local grok_home="$1" config_path candidate
+    [[ -d "$grok_home" && ! -L "$grok_home" ]] || return 1
+    # Grok 1.0.4 owns config.toml and lazily populates provider-required
+    # sections. Replacing it before every inventory makes the first probe look
+    # logged out. Keep the runner contract in a separate atomic manifest; the
+    # actual agent surface remains pinned by per-invocation CLI arguments.
+    config_path="$grok_home/.ai-consultants-policy.json"
+    candidate=$(mktemp "$grok_home/.ai-consultants-policy.json.XXXXXX") || return 1
+    if ! jq -n '{
+        schema:"ai_consultants_grok_policy_v1",
+        compatibility_imports:false,
+        workflows:false,
+        memory:false,
+        subagents:false,
+        web:false,
+        tools:[],
+        permission_mode:"dontAsk",
+        sandbox:"strict"
+      }' > "$candidate"; then
+        rm -f -- "$candidate"
+        return 1
+    fi
+    if ! chmod 600 "$candidate" || ! mv -f "$candidate" "$config_path"; then
+        rm -f -- "$candidate"
+        return 1
+    fi
+}
+
+grok_oauth_read_marker() {
+    local marker="$GROK_OAUTH_SHARED_ROOT/sync-marker.json"
+    [[ -f "$marker" && ! -L "$marker" ]] || return 1
+    jq -re '
+        select(.schema == "ai_consultants_grok_shared_oauth_marker_v1") |
+        select((.generation | type == "string" and test("^gen-[0-9]+-[0-9]+$")) and
+               (.synced_sha256 | type == "string" and test("^[0-9a-f]{64}$"))) |
+        "\(.generation) \(.synced_sha256)"
+    ' "$marker" 2>/dev/null
+}
+
+grok_oauth_write_marker() {
+    local generation="$1" synced_sha256="$2" candidate
+    candidate=$(mktemp "$GROK_OAUTH_SHARED_ROOT/.sync-marker.json.XXXXXX") || return 1
+    if ! jq -n --arg generation "$generation" --arg synced_sha256 "$synced_sha256" '
+        {schema:"ai_consultants_grok_shared_oauth_marker_v1",
+         generation:$generation,synced_sha256:$synced_sha256}
+    ' > "$candidate" || ! chmod 600 "$candidate" ||
+       ! mv -f "$candidate" "$GROK_OAUTH_SHARED_ROOT/sync-marker.json"; then
+        rm -f -- "$candidate"
+        return 1
+    fi
+}
+
+grok_oauth_generation_has_legacy_config() {
+    local config="$1/config.toml"
+    [[ -f "$config" && ! -L "$config" ]] || return 1
+    grep -q '^\[compat\.claude\]$' "$config" &&
+        grep -q '^\[compat\.cursor\]$' "$config" &&
+        grep -q '^\[workflows\]$' "$config" &&
+        grep -q '^enabled = false$' "$config"
+}
+
+grok_oauth_init() {
+    local source_home="$1"
+    GROK_OAUTH_ERROR=""
+    GROK_OAUTH_ACTIVE_HOME=""
+    GROK_OAUTH_GENERATION=""
+    GROK_OAUTH_BASELINE_HASH=""
+    GROK_OAUTH_SYNC_STATUS="not_attempted"
+    case "$GROK_OAUTH_MODE" in
+        shared|serialized) ;;
+        *) GROK_OAUTH_ERROR="Invalid GROK_OAUTH_MODE (expected shared or serialized)"; return 1 ;;
+    esac
+    if [[ ! -d "$source_home" ]]; then
+        GROK_OAUTH_ERROR="Grok OAuth home is missing"
+        return 2
+    elif [[ -L "$source_home" ]]; then
+        GROK_OAUTH_ERROR="Grok OAuth home is unsafe"
+        return 1
+    fi
+    GROK_OAUTH_SOURCE_HOME=$(cd "$source_home" && pwd -P) || {
+        GROK_OAUTH_ERROR="Could not resolve the Grok OAuth home"
+        return 1
+    }
+    GROK_OAUTH_SHARED_ROOT="${_AI_CONSULTANTS_XDG_DATA}/grok-shared-oauth"
+    if [[ ! -f "$GROK_OAUTH_SOURCE_HOME/auth.json" ]]; then
+        GROK_OAUTH_ERROR="Grok OAuth credential is missing"
+        return 2
+    elif ! grok_oauth_credential_valid "$GROK_OAUTH_SOURCE_HOME/auth.json"; then
+        GROK_OAUTH_ERROR="Grok OAuth credential is malformed"
+        return 1
+    fi
+    grok_oauth_digest "$GROK_OAUTH_SOURCE_HOME/auth.json" >/dev/null || {
+        GROK_OAUTH_ERROR="SHA-256 support is required for Grok OAuth reconciliation"
+        return 1
+    }
+}
+
+grok_oauth_seed_shared() {
+    local marker="" marker_generation="" marker_sha="" ambient_hash generation generation_dir
+    local lock_rc=0
+    if [[ -e "$GROK_OAUTH_SHARED_ROOT" &&
+          ( ! -d "$GROK_OAUTH_SHARED_ROOT" || -L "$GROK_OAUTH_SHARED_ROOT" ) ]]; then
+        GROK_OAUTH_ERROR="Shared Grok OAuth root is unsafe"
+        return 1
+    fi
+    if ! mkdir -p "$GROK_OAUTH_SHARED_ROOT" || ! chmod 700 "$GROK_OAUTH_SHARED_ROOT"; then
+        GROK_OAUTH_ERROR="Could not create the shared Grok OAuth root"
+        return 1
+    fi
+    grok_oauth_acquire_lock_wait || lock_rc=$?
+    if [[ "$lock_rc" -eq 2 ]]; then
+        GROK_OAUTH_ERROR="Another Grok invocation is reconciling OAuth state"
+        return 2
+    elif [[ "$lock_rc" -ne 0 ]]; then
+        GROK_OAUTH_ERROR="Could not secure Grok OAuth state"
+        return 1
+    fi
+
+    if ! grok_oauth_credential_valid "$GROK_OAUTH_SOURCE_HOME/auth.json"; then
+        GROK_OAUTH_ERROR="Ambient Grok OAuth credential changed or became malformed during adoption"
+        grok_oauth_release_lock
+        return 1
+    fi
+    ambient_hash=$(grok_oauth_digest "$GROK_OAUTH_SOURCE_HOME/auth.json") || {
+        GROK_OAUTH_ERROR="Could not fingerprint the ambient Grok OAuth credential"
+        grok_oauth_release_lock
+        return 1
+    }
+    if marker=$(grok_oauth_read_marker); then
+        marker_generation=${marker%% *}
+        marker_sha=${marker##* }
+    fi
+
+    generation_dir="$GROK_OAUTH_SHARED_ROOT/$marker_generation"
+    if [[ -n "$marker_generation" && "$marker_sha" == "$ambient_hash" &&
+          -d "$generation_dir" && ! -L "$generation_dir" ]] &&
+       ! grok_oauth_generation_has_legacy_config "$generation_dir" &&
+       grok_oauth_credential_valid "$generation_dir/auth.json"; then
+        GROK_OAUTH_GENERATION="$marker_generation"
+        if ! grok_oauth_write_controlled_config "$generation_dir"; then
+            GROK_OAUTH_ERROR="Could not reconcile shared Grok configuration"
+            grok_oauth_release_lock
+            return 1
+        fi
+    else
+        generation="gen-$(date +%s)-$$"
+        generation_dir="$GROK_OAUTH_SHARED_ROOT/$generation"
+        if [[ -e "$generation_dir" || -L "$generation_dir" ]] ||
+           ! mkdir "$generation_dir" || ! chmod 700 "$generation_dir"; then
+            GROK_OAUTH_ERROR="Could not create a shared Grok OAuth generation"
+            grok_oauth_release_lock
+            return 1
+        fi
+        if ! cp "$GROK_OAUTH_SOURCE_HOME/auth.json" "$generation_dir/auth.json" ||
+           ! chmod 600 "$generation_dir/auth.json" ||
+           ! grok_oauth_credential_valid "$generation_dir/auth.json" ||
+           ! grok_oauth_write_controlled_config "$generation_dir" ||
+           ! grok_oauth_write_marker "$generation" "$ambient_hash"; then
+            GROK_OAUTH_ERROR="Could not seed a shared Grok OAuth generation"
+            grok_oauth_release_lock
+            return 1
+        fi
+        GROK_OAUTH_GENERATION="$generation"
+    fi
+    grok_oauth_release_lock
+    GROK_OAUTH_ACTIVE_HOME=$(cd "$GROK_OAUTH_SHARED_ROOT/$GROK_OAUTH_GENERATION" && pwd -P) || {
+        GROK_OAUTH_ERROR="Could not resolve the shared Grok OAuth generation"
+        return 1
+    }
+}
+
+grok_oauth_seed_serialized() {
+    local isolated_grok_home="$1" lock_rc=0
+    grok_oauth_acquire_lock_wait || lock_rc=$?
+    if [[ "$lock_rc" -eq 2 ]]; then
+        GROK_OAUTH_ERROR="Another Grok invocation is using serialized OAuth mode"
+        return 2
+    elif [[ "$lock_rc" -ne 0 ]]; then
+        GROK_OAUTH_ERROR="Could not secure Grok OAuth state"
+        return 1
+    fi
+    if ! grok_oauth_credential_valid "$GROK_OAUTH_SOURCE_HOME/auth.json" ||
+       ! mkdir -p "$isolated_grok_home" || ! chmod 700 "$isolated_grok_home" ||
+       ! cp "$GROK_OAUTH_SOURCE_HOME/auth.json" "$isolated_grok_home/auth.json" ||
+       ! chmod 600 "$isolated_grok_home/auth.json" ||
+       ! grok_oauth_credential_valid "$isolated_grok_home/auth.json" ||
+       ! grok_oauth_write_controlled_config "$isolated_grok_home"; then
+        GROK_OAUTH_ERROR="Could not seed serialized Grok OAuth state"
+        grok_oauth_release_lock
+        return 1
+    fi
+    GROK_OAUTH_BASELINE_HASH=$(grok_oauth_digest "$GROK_OAUTH_SOURCE_HOME/auth.json") || {
+        GROK_OAUTH_ERROR="Could not fingerprint serialized Grok OAuth state"
+        grok_oauth_release_lock
+        return 1
+    }
+    GROK_OAUTH_ACTIVE_HOME="$isolated_grok_home"
+}
+
+grok_oauth_prepare() {
+    local isolated_grok_home="$1"
+    if [[ "$GROK_OAUTH_MODE" == "shared" ]]; then
+        grok_oauth_seed_shared
+    else
+        grok_oauth_seed_serialized "$isolated_grok_home"
+    fi
+}
+
+# Grok 1.0.4 lazily creates metadata, caches, DBs, and managed config the first
+# time a new GROK_HOME reaches the authenticated inventory. Its own locks cover
+# individual files but two pristine homes entering that bootstrap concurrently
+# can both report authentication unavailable. Serialize this one-time seed
+# only; the sentinel keeps every later capability probe and inference parallel.
+grok_oauth_bootstrap_shared() {
+    local probe_home="$1" grok_cmd="$2"
+    local sentinel="$GROK_OAUTH_ACTIVE_HOME/.ai-consultants-ready.json"
+    local candidate models lock_rc=0
+    [[ "$GROK_OAUTH_MODE" == "shared" ]] || return 0
+    if [[ -f "$sentinel" && ! -L "$sentinel" ]] &&
+       jq -e --arg generation "$GROK_OAUTH_GENERATION" '
+         .schema == "ai_consultants_grok_home_ready_v1" and
+         .generation == $generation
+       ' "$sentinel" >/dev/null 2>&1; then
+        return 0
+    fi
+
+    grok_oauth_acquire_lock_wait || lock_rc=$?
+    if [[ "$lock_rc" -eq 2 ]]; then
+        GROK_OAUTH_ERROR="Another Grok invocation is bootstrapping shared OAuth state"
+        return 2
+    elif [[ "$lock_rc" -ne 0 ]]; then
+        GROK_OAUTH_ERROR="Could not secure shared Grok OAuth bootstrap"
+        return 1
+    fi
+    if [[ -f "$sentinel" && ! -L "$sentinel" ]] &&
+       jq -e --arg generation "$GROK_OAUTH_GENERATION" '
+         .schema == "ai_consultants_grok_home_ready_v1" and
+         .generation == $generation
+       ' "$sentinel" >/dev/null 2>&1; then
+        grok_oauth_release_lock
+        return 0
+    fi
+
+    if ! models=$(run_with_timeout "$GROK_OAUTH_BOOTSTRAP_TIMEOUT_SECONDS" \
+        env HOME="$probe_home" GROK_HOME="$GROK_OAUTH_ACTIVE_HOME" \
+        "$grok_cmd" models 2>&1); then
+        if grep -Eiq 'not logged in|logged out|login required|authentication required|unauthorized|run .?grok login|status.?401' <<< "$models"; then
+            GROK_OAUTH_ERROR="Grok Build authentication unavailable"
+            grok_oauth_release_lock
+            return 4
+        fi
+        GROK_OAUTH_ERROR="Shared Grok OAuth bootstrap could not authenticate"
+        grok_oauth_release_lock
+        return 1
+    fi
+    # This call exists only to let a pristine provider home finish its lazy
+    # initialization. The adapter's normal model probe immediately follows and
+    # remains the single authority for authenticated inventory/model identity;
+    # first-run provider output is not stable enough to validate twice here.
+    if ! grok_oauth_credential_valid "$GROK_OAUTH_ACTIVE_HOME/auth.json"; then
+        GROK_OAUTH_ERROR="Shared Grok OAuth bootstrap returned invalid state"
+        grok_oauth_release_lock
+        return 1
+    fi
+    candidate=$(mktemp "$GROK_OAUTH_ACTIVE_HOME/.ai-consultants-ready.json.XXXXXX") || {
+        GROK_OAUTH_ERROR="Could not stage shared Grok OAuth readiness"
+        grok_oauth_release_lock
+        return 1
+    }
+    if ! jq -n --arg generation "$GROK_OAUTH_GENERATION" '
+        {schema:"ai_consultants_grok_home_ready_v1",generation:$generation}
+      ' > "$candidate" || ! chmod 600 "$candidate" || ! mv -f "$candidate" "$sentinel"; then
+        rm -f -- "$candidate"
+        GROK_OAUTH_ERROR="Could not record shared Grok OAuth readiness"
+        grok_oauth_release_lock
+        return 1
+    fi
+    grok_oauth_release_lock
+}
+
+grok_oauth_publish_shared() {
+    local marker marker_generation marker_sha shared_hash ambient_hash candidate lock_rc=0 rc=0
+    grok_oauth_acquire_lock_wait || lock_rc=$?
+    [[ "$lock_rc" -ne 2 ]] || return 3
+    [[ "$lock_rc" -eq 0 ]] || return 1
+
+    if ! marker=$(grok_oauth_read_marker); then
+        rc=1
+    else
+        marker_generation=${marker%% *}
+        marker_sha=${marker##* }
+        if [[ "$marker_generation" != "$GROK_OAUTH_GENERATION" ]]; then
+            rc=2
+        elif ! grok_oauth_credential_valid "$GROK_OAUTH_ACTIVE_HOME/auth.json" ||
+             ! shared_hash=$(grok_oauth_digest "$GROK_OAUTH_ACTIVE_HOME/auth.json"); then
+            rc=1
+        elif ! grok_oauth_credential_valid "$GROK_OAUTH_SOURCE_HOME/auth.json" ||
+             ! ambient_hash=$(grok_oauth_digest "$GROK_OAUTH_SOURCE_HOME/auth.json"); then
+            rc=2
+        elif [[ "$ambient_hash" != "$marker_sha" ]]; then
+            rc=2
+        elif [[ "$shared_hash" == "$marker_sha" ]]; then
+            rc=0
+        else
+            candidate=$(mktemp "$GROK_OAUTH_SOURCE_HOME/.auth.json.ai-consultants.XXXXXX") || rc=1
+            if [[ "$rc" -eq 0 ]]; then
+                if cp "$GROK_OAUTH_ACTIVE_HOME/auth.json" "$candidate" &&
+                   chmod 600 "$candidate" &&
+                   mv -f "$candidate" "$GROK_OAUTH_SOURCE_HOME/auth.json" &&
+                   grok_oauth_write_marker "$GROK_OAUTH_GENERATION" "$shared_hash"; then
+                    rc=0
+                else
+                    rm -f -- "$candidate"
+                    rc=1
+                fi
+            fi
+        fi
+    fi
+    grok_oauth_release_lock
+    return "$rc"
+}
+
+grok_oauth_publish_serialized() {
+    local scratch_hash ambient_hash candidate
+    grok_oauth_credential_valid "$GROK_OAUTH_ACTIVE_HOME/auth.json" || return 1
+    scratch_hash=$(grok_oauth_digest "$GROK_OAUTH_ACTIVE_HOME/auth.json") || return 1
+    grok_oauth_credential_valid "$GROK_OAUTH_SOURCE_HOME/auth.json" || return 2
+    ambient_hash=$(grok_oauth_digest "$GROK_OAUTH_SOURCE_HOME/auth.json") || return 1
+    [[ "$ambient_hash" == "$GROK_OAUTH_BASELINE_HASH" ]] || return 2
+    [[ "$scratch_hash" != "$GROK_OAUTH_BASELINE_HASH" ]] || return 0
+    candidate=$(mktemp "$GROK_OAUTH_SOURCE_HOME/.auth.json.ai-consultants.XXXXXX") || return 1
+    if ! cp "$GROK_OAUTH_ACTIVE_HOME/auth.json" "$candidate" ||
+       ! chmod 600 "$candidate" ||
+       ! mv -f "$candidate" "$GROK_OAUTH_SOURCE_HOME/auth.json"; then
+        rm -f -- "$candidate"
+        return 1
+    fi
+}
+
+grok_oauth_sync() {
+    local rc=0
+    if [[ "$GROK_OAUTH_MODE" == "shared" ]]; then
+        grok_oauth_publish_shared || rc=$?
+    else
+        grok_oauth_publish_serialized || rc=$?
+    fi
+    grok_oauth_release_lock
+    case "$rc" in
+        0) GROK_OAUTH_SYNC_STATUS="ok" ;;
+        2) GROK_OAUTH_SYNC_STATUS="conflict" ;;
+        3) GROK_OAUTH_SYNC_STATUS="lock_busy" ;;
+        *) GROK_OAUTH_SYNC_STATUS="failed" ;;
+    esac
+    return "$rc"
+}

package/scripts/query_grok.sh

@@ -12,6 +12,7 @@
 #   GROK_API_KEY    - xAI API key used by the fallback
 #   XAI_API_KEY     - Official xAI key name; accepted as a GROK_API_KEY alias
 #   GROK_REASONING_EFFORT - Optional CLI/API effort; max_quality sets xhigh
+#   GROK_OAUTH_MODE - shared (default, concurrent) or serialized (diagnostic)
 #   ENABLE_PERSONA  - Enable "The Provocateur" persona (default: true)
 
 set -euo pipefail
@@ -19,6 +20,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/lib/common.sh"
 source "$SCRIPT_DIR/lib/personas.sh"
+source "$SCRIPT_DIR/lib/grok_oauth.sh"
 
 QUERY="${1:-}"
 CONTEXT_FILE="${2:-}"
@@ -46,6 +48,8 @@ GROK_CLI_EFFORT=""
 _GROK_CAPABILITY_ERROR=""
 _GROK_REQUEST_LAUNCHED=false
 _GROK_MODEL_PROBE_ERROR=""
+_GROK_OAUTH_PREPARED=false
+_GROK_OAUTH_FAILURE=false
 exit_code=1
 
 if ! [[ "$GROK_MAX_TURNS" =~ ^[1-9][0-9]*$ ]]; then
@@ -57,6 +61,7 @@ if ! [[ "$GROK_MAX_TURNS" =~ ^[1-9][0-9]*$ ]]; then
 fi
 
 cleanup() {
+    grok_oauth_release_lock
     rm -f "$TEMP_OUTPUT" "${TEMP_OUTPUT}.err"
 
     # GROK_RUNTIME_DIR is always created by this script under the system temp
@@ -103,7 +108,8 @@ grok_cli_supports_required_interface() {
     local probe_workspace="$3"
     local help flag
 
-    help=$(env HOME="$probe_home" GROK_HOME="$probe_grok_home" \
+    help=$(run_with_timeout "$GROK_OAUTH_BOOTSTRAP_TIMEOUT_SECONDS" \
+        env HOME="$probe_home" GROK_HOME="$probe_grok_home" \
         "$GROK_CMD" --help 2>&1 || true)
     for flag in \
         --prompt-file --model --cwd --output-format --no-plan --no-subagents \
@@ -156,7 +162,8 @@ grok_cli_supports_required_interface() {
 
     # Exercise the complete headless argument surface under --help. This checks
     # parser compatibility without starting a session or sending a prompt.
-    "${probe_args[@]}" --help >/dev/null 2>&1 || return 1
+    run_with_timeout "$GROK_OAUTH_BOOTSTRAP_TIMEOUT_SECONDS" \
+        "${probe_args[@]}" --help >/dev/null 2>&1 || return 1
 
     if grep -q -- '--no-auto-update' <<< "$help"; then
         GROK_SUPPORTS_NO_AUTO_UPDATE=true
@@ -166,22 +173,29 @@ grok_cli_supports_required_interface() {
     GROK_CLI_COMPATIBILITY="capability-probed"
 }
 
+grok_capability_probe_with_oauth_coordination() {
+    # Capability parsing is provider-free and must not initialize either the
+    # shared OAuth home or the HOME later used for authenticated inventory.
+    grok_cli_supports_required_interface "$1" "$2" "$3"
+}
+
 grok_cli_exposes_requested_model() {
     local isolated_home="$1"
     local isolated_grok_home="$2"
     local models
 
-    if ! models=$(env HOME="$isolated_home" GROK_HOME="$isolated_grok_home" \
+    if ! models=$(run_with_timeout "$GROK_OAUTH_BOOTSTRAP_TIMEOUT_SECONDS" \
+            env HOME="$isolated_home" GROK_HOME="$isolated_grok_home" \
             "$GROK_CMD" models 2>&1); then
         if grep -Eiq 'auth|log ?in|credential|token|401|unauthor' <<<"$models"; then
-            _GROK_MODEL_PROBE_ERROR="Grok Build CLI authentication unavailable"
+            _GROK_MODEL_PROBE_ERROR="Grok Build CLI authentication unavailable (inventory_command_failed_auth)"
         else
-            _GROK_MODEL_PROBE_ERROR="Grok Build CLI model inventory failed"
+            _GROK_MODEL_PROBE_ERROR="Grok Build CLI model inventory failed (inventory_command_failed)"
         fi
         return 1
     fi
-    grep -Fq "You are logged in with grok.com." <<< "$models" || {
-        _GROK_MODEL_PROBE_ERROR="Grok Build CLI authentication unavailable"
+    grok_oauth_credential_valid "$isolated_grok_home/auth.json" || {
+        _GROK_MODEL_PROBE_ERROR="Grok Build CLI authentication unavailable (credential_invalid_after_inventory)"
         return 1
     }
     if ! awk -v requested="$GROK_MODEL" '
@@ -193,12 +207,39 @@ grok_cli_exposes_requested_model() {
         }
         END { exit(found ? 0 : 1) }
     ' <<< "$models"; then
-        _GROK_MODEL_PROBE_ERROR="Grok Build CLI does not expose the requested model $GROK_MODEL"
+        _GROK_MODEL_PROBE_ERROR="Grok Build CLI does not expose the requested model $GROK_MODEL (requested_model_missing)"
         return 1
     fi
     return 0
 }
 
+grok_model_probe_with_oauth_coordination() {
+    local isolated_home="$1" isolated_grok_home="$2" lock_rc=0 probe_rc=0
+    if [[ "$GROK_OAUTH_MODE" != "shared" ]]; then
+        grok_cli_exposes_requested_model "$isolated_home" "$isolated_grok_home"
+        return $?
+    fi
+    grok_oauth_acquire_lock_wait || lock_rc=$?
+    if [[ "$lock_rc" -ne 0 ]]; then
+        _GROK_OAUTH_FAILURE=true
+        if [[ "$lock_rc" -eq 2 ]]; then
+            _GROK_MODEL_PROBE_ERROR="Grok OAuth inventory coordination is temporarily busy"
+        else
+            _GROK_MODEL_PROBE_ERROR="Grok OAuth inventory coordination failed"
+        fi
+        return 1
+    fi
+    grok_cli_exposes_requested_model "$isolated_home" "$isolated_grok_home" || probe_rc=$?
+    grok_oauth_release_lock
+    return "$probe_rc"
+}
+
+grok_shared_oauth_bootstrap_ready() {
+    oauth_rc=0
+    grok_oauth_bootstrap_shared "$1" "$GROK_CMD" || oauth_rc=$?
+    [[ "$oauth_rc" -eq 0 ]]
+}
+
 grok_cli_is_unavailable() {
     local cli_exit_code="$1"
     local error_file="$2"
@@ -241,34 +282,81 @@ else
         isolated_home="$GROK_RUNTIME_DIR/home"
         isolated_grok_home="$isolated_home/.grok"
         isolated_workspace="$GROK_RUNTIME_DIR/workspace"
+        capability_home="$GROK_RUNTIME_DIR/capability-home"
+        capability_grok_home="$capability_home/.grok"
+        capability_workspace="$GROK_RUNTIME_DIR/capability-workspace"
         prompt_file="$GROK_RUNTIME_DIR/prompt.txt"
-        mkdir -p "$isolated_grok_home" "$isolated_workspace"
-        chmod 700 "$isolated_home" "$isolated_grok_home" "$isolated_workspace"
+        mkdir -p "$isolated_home" "$isolated_workspace" \
+            "$capability_grok_home" "$capability_workspace"
+        chmod 700 "$isolated_home" "$isolated_workspace" \
+            "$capability_home" "$capability_grok_home" "$capability_workspace"
+        _GROK_CAPABILITY_HOME_READY=true
+        grok_oauth_write_controlled_config "$capability_grok_home" || {
+            printf '%s\n' "Grok capability home could not be initialized" > "${TEMP_OUTPUT}.err"
+            _GROK_OAUTH_FAILURE=true
+            _GROK_CAPABILITY_HOME_READY=false
+            exit_code=70
+        }
         printf '%s' "$FULL_QUERY" > "$prompt_file"
         chmod 600 "$prompt_file"
 
-        # Preserve only the credential needed to use the installed CLI. All
-        # config, plugins, hooks, MCP servers, skills, memories, and project
-        # instructions stay outside the isolated HOME/CWD.
+        # Preserve a rotating subscription credential without sharing agent
+        # state. HOME/CWD/prompt/output remain per invocation. In shared mode,
+        # concurrent processes use one runner-owned GROK_HOME so Grok Build's
+        # native auth lock can coordinate refresh. Serialized mode keeps the
+        # previous per-run GROK_HOME shape under a full diagnostic lock.
         source_grok_home=$(printenv GROK_HOME 2>/dev/null || true)
         [[ -n "$source_grok_home" ]] || source_grok_home="${HOME}/.grok"
-        if [[ -f "$source_grok_home/auth.json" && ! -L "$source_grok_home/auth.json" ]]; then
-            if cp "$source_grok_home/auth.json" "$isolated_grok_home/auth.json"; then
-                chmod 600 "$isolated_grok_home/auth.json"
+        if [[ "$_GROK_CAPABILITY_HOME_READY" == "true" ]]; then
+            oauth_rc=0
+            grok_oauth_init "$source_grok_home" || oauth_rc=$?
+            if [[ "$oauth_rc" -eq 2 ]]; then
+                printf '%s\n' "Grok Build authentication unavailable; run grok login" > "${TEMP_OUTPUT}.err"
+                log_warn "[$CONSULTANT_NAME] Grok Build authentication unavailable"
+                exit_code=69
+            elif [[ "$oauth_rc" -ne 0 ]]; then
+                _GROK_OAUTH_FAILURE=true
+                printf '%s\n' "Grok OAuth state failed validation" > "${TEMP_OUTPUT}.err"
+                log_warn "[$CONSULTANT_NAME] $GROK_OAUTH_ERROR"
+                exit_code=70
             else
-                log_warn "[$CONSULTANT_NAME] Could not copy the Grok CLI credential into the isolated runtime"
+                oauth_rc=0
+                grok_oauth_prepare "$isolated_grok_home" || oauth_rc=$?
+                if [[ "$oauth_rc" -ne 0 ]]; then
+                    _GROK_OAUTH_FAILURE=true
+                    printf '%s\n' "Grok OAuth state could not be prepared" > "${TEMP_OUTPUT}.err"
+                    log_warn "[$CONSULTANT_NAME] $GROK_OAUTH_ERROR"
+                    [[ "$oauth_rc" -eq 2 ]] && exit_code=75 || exit_code=70
+                else
+                    _GROK_OAUTH_PREPARED=true
+                fi
             fi
         fi
 
         GROK_CLI_VERSION=$(observe_grok_cli_version)
-        if ! grok_cli_supports_required_interface \
-                "$isolated_home" "$isolated_grok_home" "$isolated_workspace"; then
+        if [[ "$_GROK_OAUTH_PREPARED" != "true" ]]; then
+            :
+        elif ! grok_capability_probe_with_oauth_coordination \
+                "$capability_home" "$capability_grok_home" "$capability_workspace"; then
             GROK_CLI_COMPATIBILITY="incompatible"
             printf '%s\n' "${_GROK_CAPABILITY_ERROR:-Grok Build CLI lacks the required capabilities}" > "${TEMP_OUTPUT}.err"
             log_warn "[$CONSULTANT_NAME] ${_GROK_CAPABILITY_ERROR:-Grok Build CLI lacks the required capabilities} (reported version: $GROK_CLI_VERSION)"
             exit_code=69
-        elif ! grok_cli_exposes_requested_model \
-                "$isolated_home" "$isolated_grok_home" > "${TEMP_OUTPUT}.err"; then
+        elif [[ "$GROK_OAUTH_MODE" == "shared" ]] &&
+             ! grok_shared_oauth_bootstrap_ready "$isolated_home"; then
+            _GROK_OAUTH_PREPARED=false
+            if [[ "$oauth_rc" -eq 4 ]]; then
+                printf '%s\n' "Grok Build authentication unavailable; run grok login" > "${TEMP_OUTPUT}.err"
+                log_warn "[$CONSULTANT_NAME] Grok Build authentication unavailable"
+                exit_code=69
+            else
+                _GROK_OAUTH_FAILURE=true
+                printf '%s\n' "Grok shared OAuth bootstrap failed" > "${TEMP_OUTPUT}.err"
+                log_warn "[$CONSULTANT_NAME] $GROK_OAUTH_ERROR"
+                [[ "$oauth_rc" -eq 2 ]] && exit_code=75 || exit_code=70
+            fi
+        elif ! grok_model_probe_with_oauth_coordination \
+                "$isolated_home" "$GROK_OAUTH_ACTIVE_HOME" > "${TEMP_OUTPUT}.err"; then
             printf '%s\n' "${_GROK_MODEL_PROBE_ERROR:-Grok Build CLI model inventory failed}" > "${TEMP_OUTPUT}.err"
             log_warn "[$CONSULTANT_NAME] ${_GROK_MODEL_PROBE_ERROR:-Grok Build CLI model inventory failed}"
             exit_code=69
@@ -280,7 +368,7 @@ else
             GROK_ARGS=(
                 env
                 HOME="$isolated_home"
-                GROK_HOME="$isolated_grok_home"
+                GROK_HOME="$GROK_OAUTH_ACTIVE_HOME"
                 "$GROK_CMD"
                 --prompt-file "$prompt_file"
                 -m "$GROK_MODEL"
@@ -314,7 +402,7 @@ else
             fi
 
             _GROK_REQUEST_LAUNCHED=true
-            if run_query \
+            if RUN_QUERY_REDACT_ERRORS=true run_query \
                     "$CONSULTANT_NAME" \
                     "$TEMP_OUTPUT" \
                     "$GROK_TIMEOUT_SECONDS" \
@@ -324,6 +412,35 @@ else
                 exit_code=$?
             fi
         fi
+
+        # Publish refreshes before considering fallback or publishing output.
+        # A concurrent external `grok login` changes the ambient digest, wins
+        # the CAS, and makes this run fail temporarily without overwriting it.
+        if [[ "$_GROK_OAUTH_PREPARED" == "true" ]]; then
+            oauth_rc=0
+            grok_oauth_sync || oauth_rc=$?
+            if [[ "$oauth_rc" -ne 0 ]]; then
+                _GROK_OAUTH_FAILURE=true
+                : > "$TEMP_OUTPUT"
+                case "$oauth_rc" in
+                    2)
+                        printf '%s\n' "Grok OAuth changed concurrently; retry" > "${TEMP_OUTPUT}.err"
+                        log_warn "[$CONSULTANT_NAME] External Grok login superseded this run"
+                        exit_code=75
+                        ;;
+                    3)
+                        printf '%s\n' "Grok OAuth reconciliation lock is busy; retry" > "${TEMP_OUTPUT}.err"
+                        log_warn "[$CONSULTANT_NAME] Grok OAuth reconciliation is temporarily busy"
+                        exit_code=75
+                        ;;
+                    *)
+                        printf '%s\n' "Grok OAuth refresh could not be persisted" > "${TEMP_OUTPUT}.err"
+                        log_warn "[$CONSULTANT_NAME] Grok OAuth refresh could not be persisted"
+                        exit_code=70
+                        ;;
+                esac
+            fi
+        fi
     else
         log_warn "[$CONSULTANT_NAME] Grok Build CLI not found: $GROK_CMD"
         exit_code=127
@@ -334,6 +451,7 @@ else
     # it cannot silently turn into a separately billed API request.
     if [[ $exit_code -ne 0 ]] \
             && [[ "$_GROK_REQUEST_LAUNCHED" != "true" ]] \
+            && [[ "$_GROK_OAUTH_FAILURE" != "true" ]] \
             && grok_cli_is_unavailable "$exit_code" "${TEMP_OUTPUT}.err" \
             && [[ -n "${GROK_API_KEY:-}" ]]; then
         log_warn "[$CONSULTANT_NAME] Grok Build CLI unavailable (exit $exit_code); falling back to the xAI API"