fix(grok): updater isolation, api-key no-mount, entrypoint coverage

Review hardening for #404 (thanks Codex + two deep review passes):

- tmpfs over ~/.grok/bin and ~/.grok/downloads whenever a host dir is
  mounted at /home/deva/.grok. Reproduced against real 0.2.93: a mounted
  config.toml without postinstall's `[cli] installer = "npm"` marker
  flips the updater to installer=internal, and `grok update` re-creates
  both dirs ON THE HOST MOUNT — a Linux binary that shadows a macOS
  host CLI via the host npm trampoline. Updater writes now die with
  the container; verified live (mount stack + host-side clean).
- api-key mode mounts no ~/.grok, per the #403 spec. grok credential
  priority is model.api_key > model.env_key > session token >
  XAI_API_KEY, so anything a mounted config carries can outrank — and
  bill instead of — the exported key. Blank auth.json overlay kept as
  defense for explicit -v mounts.
- docker-entrypoint.sh: grok version header, verbose diagnostics, and
  binary presence check (#403 scope, was missing).
- test-mount-shape.sh: grok in hybrid/default loops; new assertions for
  the update guard and api-key no-mount.
- docs/authentication.md, CHANGELOG, DEV-LOGS: correct the false
  "grok update is a no-op" claim; document the real behavior.

Refs #403

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: lroolle

CHANGELOG.md

@@ -18,13 +18,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   fourth first-party agent (#403). `deva.sh grok` runs it YOLO-style
   (`--always-approve`) in the standard container shape. Auth: `oauth`
   (default, mounts `~/.grok`; in-container first login via
-  `grok login --device-auth`) or `api-key` (`XAI_API_KEY`). In api-key mode
-  the default `auth.json` is masked with a blank overlay because grok
-  prefers a session token over the env key. Grok's npm launcher resolves
-  `~/.grok/bin/grok` (its self-update dir) before the packaged binary, so
-  the image moves the real binary to `~/.local/bin` and drops `~/.grok/bin`
-  — a host-mounted `~/.grok`, possibly holding a macOS binary, can never
-  shadow the container CLI. Pin:
+  `grok login --device-auth`) or `api-key` (`XAI_API_KEY`). api-key mode
+  mounts no `~/.grok` at all: grok's credential priority (`model.api_key` >
+  `model.env_key` > session token > `XAI_API_KEY`) means anything a mounted
+  config carries could outrank — and bill instead of — the exported key.
+  Grok's npm launcher resolves `~/.grok/bin/grok` (its self-update dir)
+  before the packaged binary, so the image moves the real binary to
+  `~/.local/bin` and drops `~/.grok/bin` — a host-mounted `~/.grok`,
+  possibly holding a macOS binary, can never shadow the container CLI.
+  The reverse is guarded with container-local tmpfs over `~/.grok/bin` and
+  `~/.grok/downloads` whenever a host dir is mounted there: in-container
+  `grok update` cannot write Linux binaries into the host install. Pin:
   `GROK_CLI_VERSION` in `versions.env`, label
   `org.opencontainers.image.grok_cli_version`, wired through make/CI/
   nightly/release version plumbing

DEV-LOGS.md

@@ -17,10 +17,12 @@
 - Why: xAI shipped an official coding-agent CLI (x.ai/cli, npm @xai-official/grok); deva should launch it like claude/codex/gemini. Not to be confused with community superagent-ai/grok-cli (npm grok-dev) — different product, same bin name.
 - What:
   - agents/grok.sh: oauth default (mount ~/.grok) + api-key (XAI_API_KEY); appends --always-approve (grok's bypassPermissions alias) since the container is the sandbox
-  - deva.sh: canonical entry .grok, autolink ~/.grok, XAI_API_KEY env handling, blank-overlay /home/deva/.grok/auth.json for api-key mode (grok prefers session token over env key — overlay makes the key actually win)
+  - deva.sh: canonical entry .grok, autolink ~/.grok, XAI_API_KEY env handling. api-key mode mounts NO ~/.grok (grok credential priority: model.api_key > model.env_key > session token > XAI_API_KEY — anything a mounted config carries can outrank the exported key; per #403 spec and Codex review). Blank auth.json overlay kept as defense for explicit -v mounts
   - install-agent-tooling.sh pin_grok_platform_binary: grok's npm bin is a trampoline that resolves ~/.grok/bin/grok FIRST, and postinstall parks the ~125MB real binary there (self-update dir); a host mount would shadow it (macOS binary -> exec format error). Move the binary to ~/.local/bin, repoint the npm bin, rm ~/.grok/bin
-  - GROK_CLI_VERSION pin wired through versions.env, Makefile, Dockerfile(+rust), version-pins/upgrade/report/resolve scripts, ci/nightly/release workflows; tests extended (release-utils registry, version-upgrade mock, install-tooling, version-targets)
-- Result: deva.sh grok works with both auth modes (dry-run verified: mount + env + overlay wiring); grok pinned at 0.2.93; make versions-up picks up new upstream releases
+  - deva.sh append_grok_update_guard: the reverse hole, found in review and reproduced against the real 0.2.93 — a mounted config.toml without the postinstall's `[cli] installer = "npm"` marker flips the updater to installer=internal, and `grok update` re-creates ~/.grok/bin + ~/.grok/downloads ON THE HOST MOUNT (Linux binary shadows a macOS host CLI via the host trampoline). Fix: tmpfs over both dirs whenever a host dir lands at /home/deva/.grok; updater writes die with the container
+  - docker-entrypoint.sh: grok version header, verbose diagnostics, ensure_agent_binaries
+  - GROK_CLI_VERSION pin wired through versions.env, Makefile, Dockerfile(+rust), version-pins/upgrade/report/resolve scripts, ci/nightly/release workflows; tests extended (release-utils registry, version-upgrade mock, install-tooling, version-targets, mount-shape grok + update-guard + api-key no-mount assertions)
+- Result: deva.sh grok works with both auth modes (dry-run + mount-shape verified); grok pinned at 0.2.93; make versions-up picks up new upstream releases; host ~/.grok cannot be poisoned by in-container updates (tmpfs guard verified live: uid/gid/mode/size + noexec)
 
 # [2026-07-07] Dev Log: switch --trace default from claude-trace to cctrace
 - Why: claude-trace's node --require fetch hook only sees /v1/messages and dies on native Claude binaries; cctrace (thevibeworks/cctrace) MITM-captures everything (OAuth, usage/credits, MCP) and auto-detects npm vs native installs

agents/grok.sh

@@ -52,6 +52,9 @@ setup_grok_auth() {
                            "Set: export XAI_API_KEY=your_key (from https://console.x.ai)"
             fi
 
+            # No ~/.grok mount in this mode (grok_api_key_no_mount in
+            # deva.sh): grok resolves config credentials above XAI_API_KEY,
+            # so a mounted config.toml could silently bill another account.
             AUTH_DETAILS="api-key (XAI_API_KEY)"
             DOCKER_ARGS+=("-e" "XAI_API_KEY=$XAI_API_KEY")
             ;;

deva.sh

@@ -1976,13 +1976,49 @@ agent_canonical_basenames() {
     esac
 }
 
+# grok api-key contract (#403): pass XAI_API_KEY, mount no auth dir.
+# grok's credential priority is model.api_key > model.env_key > session
+# token > XAI_API_KEY, so anything a mounted ~/.grok carries (config.toml
+# per-model keys, auth.json session) can outrank the exported key and
+# silently bill another account.
+grok_api_key_no_mount() {
+    [ "$ACTIVE_AGENT" = "grok" ] && [ "${AUTH_METHOD:-}" = "api-key" ]
+}
+
+# grok's self-updater writes Linux binaries into ~/.grok/bin and
+# ~/.grok/downloads — inside the auth dir we bind-mount. Verified against
+# @xai-official/grok 0.2.93: a mounted config.toml without the npm installer
+# marker flips the updater to installer=internal, and `grok update` then
+# re-creates both dirs on the mount (worst case: Linux binary shadowing a
+# macOS host CLI via the host npm trampoline). Whenever a host dir lands at
+# /home/deva/.grok, overlay those two paths with container-local tmpfs so
+# updater writes die with the container instead of poisoning the host.
+append_grok_update_guard() {
+    local arg
+    for arg in "${DOCKER_ARGS[@]+"${DOCKER_ARGS[@]}"}"; do
+        case "$arg" in
+        *:/home/deva/.grok | *:/home/deva/.grok:*)
+            DOCKER_ARGS+=(
+                --tmpfs "/home/deva/.grok/bin:uid=$(id -u),gid=$(id -g),mode=0755,size=512m"
+                --tmpfs "/home/deva/.grok/downloads:uid=$(id -u),gid=$(id -g),mode=0755,size=512m"
+            )
+            return 0
+            ;;
+        esac
+    done
+    return 0
+}
+
 # Mount the canonical entries for one agent from a source directory.
 # Host-side CLI -v or .deva VOLUME= at the same container target wins
 # (user_volumes_declares_target suppression; first-writer-wins holds).
 mount_agent_canonical() {
     local agent="$1"
     local src_dir="$2"
     [ -n "$agent" ] && [ -d "$src_dir" ] || return 0
+    if [ "$agent" = "grok" ] && grok_api_key_no_mount; then
+        return 0
+    fi
 
     local entry src
     while IFS= read -r entry; do
@@ -2092,8 +2128,9 @@ default_credential_target_path() {
         printf '%s' "/home/deva/.gemini/mcp-oauth-tokens-v2.json"
         ;;
     grok)
-        # grok prefers the auth.json session token over XAI_API_KEY, so the
-        # blank overlay is what makes api-key auth win over a mounted ~/.grok.
+        # api-key mode mounts no ~/.grok (grok_api_key_no_mount), but an
+        # explicit user -v/.deva VOLUME can still carry one in; grok prefers
+        # a session token over XAI_API_KEY, so blank-overlay auth.json anyway.
         printf '%s' "/home/deva/.grok/auth.json"
         ;;
     *)
@@ -3490,7 +3527,9 @@ else
         [ -f "$HOME/.claude.json" ] && DOCKER_ARGS+=("-v" "$HOME/.claude.json:/home/deva/.claude.json")
         [ -d "$HOME/.codex" ] && DOCKER_ARGS+=("-v" "$HOME/.codex:/home/deva/.codex")
         [ -d "$HOME/.gemini" ] && DOCKER_ARGS+=("-v" "$HOME/.gemini:/home/deva/.gemini")
-        [ -d "$HOME/.grok" ] && DOCKER_ARGS+=("-v" "$HOME/.grok:/home/deva/.grok")
+        if [ -d "$HOME/.grok" ] && ! grok_api_key_no_mount; then
+            DOCKER_ARGS+=("-v" "$HOME/.grok:/home/deva/.grok")
+        fi
     fi
 fi
 _step "mount dispatch: done"
@@ -3518,6 +3557,9 @@ if [ "$CONFIG_HOME_FROM_CLI" = false ] && [ "$QUICK_MODE" = false ]; then
     fi
 fi
 
+append_grok_update_guard
+_step "append_grok_update_guard"
+
 append_user_envs
 _step "append_user_envs"
 validate_bind_mount_shape

docker-entrypoint.sh

@@ -29,6 +29,17 @@ get_codex_version() {
     echo "$version"
 }
 
+get_grok_version() {
+    local version=""
+    for path in "$DEVA_HOME/.local/bin/grok" "$(command -v grok 2>/dev/null)"; do
+        if [ -x "$path" ]; then
+            version=$($path --version 2>/dev/null | head -1)
+            break
+        fi
+    done
+    echo "$version"
+}
+
 show_environment_info() {
     local header="[deva]"
     case "$DEVA_AGENT" in
@@ -46,6 +57,13 @@ show_environment_info() {
             header+=" Codex CLI (version detection failed)"
         fi
         ;;
+    grok)
+        if [ -n "$GROK_VERSION" ]; then
+            header+=" Starting Grok ($GROK_VERSION)"
+        else
+            header+=" Grok CLI (version detection failed)"
+        fi
+        ;;
     *)
         header+=" Starting agent: $DEVA_AGENT"
         ;;
@@ -87,6 +105,28 @@ show_environment_info() {
             else
                 echo "warning: Claude auth directory not found in $DEVA_HOME/.claude"
             fi
+        elif [ "$DEVA_AGENT" = "grok" ]; then
+            local grok_path=""
+            for path in "$DEVA_HOME/.local/bin/grok" "$(command -v grok 2>/dev/null)"; do
+                if [ -x "$path" ]; then
+                    grok_path="$path"
+                    break
+                fi
+            done
+            if [ -n "$grok_path" ]; then
+                echo "Grok CLI: $($grok_path --version 2>/dev/null || echo 'Found but version failed')"
+                echo "Grok location: $grok_path"
+            else
+                echo "Grok CLI not found in PATH"
+            fi
+
+            if [ -d "$DEVA_HOME/.grok" ]; then
+                echo "Grok auth directory mounted"
+                # shellcheck disable=SC2012
+                ls -la "$DEVA_HOME/.grok" | head -5
+            else
+                echo "warning: Grok auth directory not found in $DEVA_HOME/.grok"
+            fi
         else
             local codex_path=""
             for path in "/usr/local/bin/codex" "/usr/bin/codex" "$(command -v codex 2>/dev/null)"; do
@@ -306,6 +346,12 @@ ensure_agent_binaries() {
             exit 1
         fi
         ;;
+    grok)
+        if ! command -v grok >/dev/null 2>&1; then
+            echo "error: Grok CLI not found in container"
+            exit 1
+        fi
+        ;;
     esac
 }
 
@@ -316,6 +362,7 @@ main() {
 
     CLAUDE_VERSION="$(get_claude_version)"
     CODEX_VERSION="$(get_codex_version)"
+    GROK_VERSION="$(get_grok_version)"
 
     if [ -n "$ANTHROPIC_BASE_URL" ]; then
         case "$ANTHROPIC_BASE_URL" in

docs/authentication.md

@@ -290,9 +290,15 @@ Requires:
 
 - `XAI_API_KEY` (from [console.x.ai](https://console.x.ai))
 
-Grok prefers an `auth.json` session token over `XAI_API_KEY`, so deva masks
-the default `auth.json` path with a blank overlay in this mode. The API key
-is what gets billed, even if a mounted `~/.grok` still holds a session.
+Grok's credential priority puts mounted config above the environment:
+`model.api_key` > `model.env_key` > session token > `XAI_API_KEY`. So in
+this mode deva mounts no `~/.grok` at all — the exported key is the only
+credential in the container, and it is what gets billed. Session state
+lives container-local and does not persist across runs in this mode.
+
+If you force a `~/.grok` mount with `-v` anyway, deva still blank-overlays
+the default `auth.json`, but per-model keys in a mounted `config.toml`
+outrank `XAI_API_KEY` — don't mix the two.
 
 Example:
 
@@ -306,9 +312,17 @@ deva.sh grok --auth-with api-key
 Grok keeps its real binary in `~/.grok/bin/` (its self-update dir) and the
 npm launcher resolves that path first. Inside the image, deva moves the
 binary to `~/.local/bin/grok` and removes `~/.grok/bin`, so a host-mounted
-`~/.grok` (which may contain a macOS binary) never shadows it. Consequence:
-`grok update` inside the container is a no-op for the binary actually being
-run; the image pin (`GROK_CLI_VERSION`) is the only version that matters.
+`~/.grok` (which may contain a macOS binary) never shadows it.
+
+The reverse direction is guarded too: grok's self-updater writes into
+`~/.grok/bin/` and `~/.grok/downloads/`. A mounted `config.toml` without
+the npm installer marker makes the updater treat the install as
+self-managed, so `grok update` would drop Linux binaries into the host
+mount — breaking a macOS host CLI via its npm launcher. Whenever a host
+dir is mounted at `/home/deva/.grok`, deva overlays those two paths with
+container-local tmpfs: in-container `grok update` works, its writes die
+with the container, and the host install stays intact. The image pin
+(`GROK_CLI_VERSION`) is the only version that matters.
 
 ## Config Homes And Auth Isolation
 

scripts/test-mount-shape.sh

@@ -53,20 +53,24 @@ mkdir -p \
     "$hybrid_root/xdg/deva/claude" \
     "$hybrid_root/xdg/deva/codex" \
     "$hybrid_root/xdg/deva/gemini" \
+    "$hybrid_root/xdg/deva/grok" \
     "$hybrid_root/host/.claude" \
     "$hybrid_root/host/.codex" \
     "$hybrid_root/host/.gemini" \
+    "$hybrid_root/host/.grok" \
     "$hybrid_root/cli/.codex"
 touch "$hybrid_root/host/.claude.json"
 
 ln -sf "$hybrid_root/host/.claude"      "$hybrid_root/xdg/deva/claude/.claude"
 ln -sf "$hybrid_root/host/.claude.json" "$hybrid_root/xdg/deva/claude/.claude.json"
 ln -sf "$hybrid_root/host/.codex"       "$hybrid_root/xdg/deva/codex/.codex"
 ln -sf "$hybrid_root/host/.gemini"      "$hybrid_root/xdg/deva/gemini/.gemini"
+ln -sf "$hybrid_root/host/.grok"        "$hybrid_root/xdg/deva/grok/.grok"
 
 cat > "$hybrid_root/xdg/deva/.deva" <<EOF
 VOLUME=$hybrid_root/host/.codex:/home/deva/.codex
 VOLUME=$hybrid_root/host/.gemini:/home/deva/.gemini
+VOLUME=$hybrid_root/host/.grok:/home/deva/.grok
 VOLUME=$hybrid_root/host/.claude:/home/deva/.claude
 VOLUME=$hybrid_root/host/.claude.json:/home/deva/.claude.json
 EOF
@@ -94,14 +98,14 @@ count_target() {
     fi
 }
 
-for agent in claude codex gemini; do
+for agent in claude codex gemini grok; do
     out="$(run_hybrid "$agent" --dry-run || true)"
     if grep -F -- 'duplicate bind mount target detected' <<<"$out" >/dev/null; then
         echo "hybrid recipe triggered duplicate-target error for $agent" >&2
         echo "$out" >&2
         exit 1
     fi
-    for tgt in /home/deva/.claude /home/deva/.claude.json /home/deva/.codex /home/deva/.gemini; do
+    for tgt in /home/deva/.claude /home/deva/.claude.json /home/deva/.codex /home/deva/.gemini /home/deva/.grok; do
         c="$(count_target "$tgt" "$out")"
         if [[ "$c" -ne 1 ]]; then
             echo "hybrid $agent: target $tgt emitted $c times (want 1)" >&2
@@ -152,7 +156,8 @@ trap default_cleanup EXIT
 mkdir -p \
     "$default_root/xdg/deva/claude/.claude" \
     "$default_root/xdg/deva/codex/.codex" \
-    "$default_root/xdg/deva/gemini/.gemini"
+    "$default_root/xdg/deva/gemini/.gemini" \
+    "$default_root/xdg/deva/grok/.grok"
 echo '{}' > "$default_root/xdg/deva/claude/.claude.json"
 
 run_default() {
@@ -167,9 +172,9 @@ run_default() {
     ) 2>&1
 }
 
-for agent in claude codex gemini; do
+for agent in claude codex gemini grok; do
     out="$(run_default "$agent" --dry-run || true)"
-    for tgt in /home/deva/.claude /home/deva/.claude.json /home/deva/.codex /home/deva/.gemini; do
+    for tgt in /home/deva/.claude /home/deva/.claude.json /home/deva/.codex /home/deva/.gemini /home/deva/.grok; do
         c="$(count_target "$tgt" "$out")"
         if [[ "$c" -ne 1 ]]; then
             echo "hybrid-default $agent: target $tgt emitted $c times (want 1)" >&2
@@ -179,6 +184,33 @@ for agent in claude codex gemini; do
     done
 done
 
+# ───── grok update-guard + api-key no-mount coverage ─────
+# A mounted /home/deva/.grok must come with tmpfs overlays for the
+# self-updater dirs (bin/, downloads/) so in-container `grok update`
+# cannot write into the host mount.
+grok_out="$(run_default grok --dry-run || true)"
+for guard in "--tmpfs /home/deva/.grok/bin:" "--tmpfs /home/deva/.grok/downloads:"; do
+    if ! grep -F -- "$guard" <<<"$grok_out" >/dev/null; then
+        echo "grok oauth: missing update guard $guard" >&2
+        echo "$grok_out" >&2
+        exit 1
+    fi
+done
+
+# api-key mode (#403): XAI_API_KEY only, no ~/.grok mount, no guard needed.
+apikey_out="$(XAI_API_KEY=test-key run_default grok --auth-with api-key --dry-run || true)"
+apikey_grok="$(count_target /home/deva/.grok "$apikey_out")"
+if [[ "$apikey_grok" -ne 0 ]]; then
+    echo "grok api-key: target /home/deva/.grok emitted $apikey_grok times (want 0)" >&2
+    echo "$apikey_out" >&2
+    exit 1
+fi
+if grep -F -- "--tmpfs /home/deva/.grok/bin:" <<<"$apikey_out" >/dev/null; then
+    echo "grok api-key: update guard emitted without a .grok mount" >&2
+    echo "$apikey_out" >&2
+    exit 1
+fi
+
 # Explicit --config-home DIR isolates to a single home (no sibling agents).
 iso_out="$(run_default claude --config-home "$default_root/xdg/deva/claude" --dry-run || true)"
 iso_claude="$(count_target /home/deva/.claude "$iso_out")"