codex-grok-mcp 0.2.0-beta.4 → 0.2.0-beta.6

package/CONTRIBUTING.md

@@ -4,64 +4,60 @@ Thanks for helping keep this bridge small, safe, and dependable.
 
 ## Before opening a change
 
-- Use an issue or discussion before adding tools, adapters, dependencies, authentication paths, or new supported platforms.
-- Preserve the isolated `grok_ask` boundary. Experimental persistent Bot support must stay opt-in, separately paired, and unavailable without a validated private pairing file.
-- Never include credentials, `~/.grok/auth.json`, private prompts, responses, transcripts, or unredacted logs.
-- Never scrape Grok Bot app state, decrypt descriptors, read Keychain, or infer gateway credentials.
+- Use the [bug report form](https://github.com/Fato07/codex-grok-mcp/issues/new?template=bug-report.yml) for reproducible defects.
+- Open a [feature request](https://github.com/Fato07/codex-grok-mcp/issues/new?template=feature-request.yml) before adding a tool, adapter, dependency, authentication path, or supported platform.
+- Keep `grok_ask` isolated from persistent Bot support.
+- Never commit credentials, authentication files, private prompts, responses, transcripts, or unredacted logs.
+- Never scrape Grok Bot state, decrypt descriptors, read Keychain, or infer gateway credentials.
 
 ## Local setup
 
 ```bash
 npm ci
-npm run typecheck
+npm ci --prefix relay
 npm run test:all
-npm run build
-npm run doctor
 ```
 
-Use a real live call only with your own Grok account and data you are authorized to send. Unit tests must not require network access or real authentication.
+`npm run doctor` is optional and requires a local Grok CLI login. It checks setup without sending a model request. Live tests must use your own account and data you are allowed to share; automated tests must use mocks.
 
 ## Pull requests
 
 Keep pull requests focused. Include:
 
-- the user-visible problem and why the existing behavior is insufficient;
-- the smallest implementation that fixes it;
-- one focused regression test for non-trivial behavior;
-- compatibility and security-boundary impact;
-- documentation changes when commands or behavior change;
-- upstream source and license attribution for adapted code.
+- the user-visible problem;
+- the smallest complete fix;
+- one regression test for non-trivial behavior;
+- any compatibility or security-boundary change;
+- documentation updates when commands or behavior change;
+- attribution for adapted code.
 
 Before requesting review, run:
 
 ```bash
-npm run typecheck
 npm run test:all
-python3 /path/to/plugin-creator/scripts/validate_plugin.py plugins/codex-grok-mcp
+npm audit --omit=dev
+npm audit --prefix relay
+npm pack --dry-run
 ```
 
-Do not update generated package versions in feature pull requests unless the maintainer asks. Do not add postinstall scripts or telemetry.
+Do not add postinstall scripts or telemetry. Version changes belong in release work, not ordinary feature pull requests.
 
-## Compatibility claims
+For a stable release candidate, use the single maintainer checklist in [RELEASING.md](RELEASING.md).
 
-Mocks and unit tests are not platform proof. To add a supported compatibility row, provide a redacted live smoke-test result showing the OS/architecture, Node version, Codex version, Grok CLI version, selected model, and successful response. Do not include response content.
+## Compatibility claims
 
-## New adapters and tools
+Mocks are not platform proof. A new supported environment needs a redacted live result containing OS, architecture, Node, Codex, Grok CLI, selected model, and a successful response. Do not include response content.
 
-The core `grok_ask` tool stays isolated from optional adapters. A new adapter needs:
+## Adapters and Bot tools
 
-- a documented upstream contract and operator-authorized credentials or pairing;
-- an identified maintenance owner;
-- a separate explicit configuration path;
-- tests and threat-boundary documentation;
-- no scraping, Keychain extraction, internal gateway credentials, or silent fallback.
+New adapters need a documented upstream contract, operator-authorized credentials or pairing, a maintenance owner, tests, and a separate opt-in configuration path.
 
-Persistent Grok Bot integration is accepted only through an official inbound API or a clearly separated experimental adapter.
+For persistent Bot changes, preserve exact-ID and non-group checks, bounded sanitized reads, explicit no-correlation and no-completion claims, and no automatic write retries. Bulk writes must keep the roster fingerprint, exact ordered IDs, and native confirmation. Ambiguous writes remain `outcome_unknown`; cancelled remaining recipients stay `not_attempted`.
 
-The paired bridge is the narrow exception: its bounded local client discovers the loopback gateway only inside the Grok VM; the gateway token never leaves that VM; the self-hosted relay authenticates native clients before allocation and forwards only authenticated ciphertext; the companion exposes only metadata-only status, roster listing, exact-ID bounded text/status reads, and exact-ID sends. Preserve the strict status allowlist; exact-ID and non-group checks; text-only sanitization and byte ceilings; Bot-bound opaque pagination; the untrusted-content, no-correlation, and no-completion-claim boundaries; and protocol-v3 status plus protocol-v2 reads with explicit `UPGRADE_REQUIRED` for an older companion while v1 list/send remains compatible. For writes, preserve fingerprint-bound plus native-user-confirmed `PING`-to-all, sequential one-shot delivery, cached replay receipts, per-Bot receipts, no automatic retries, `outcome_unknown` for ambiguous sends, and `not_attempted` after cancellation. Keep the legacy URL/token transport out of the default plugin environment. Tests must use mock gateways/relays; distinguish metadata-only live probes from live read or message compatibility.
+Keep the legacy URL/token adapter out of the default plugin environment. Use mock gateways and relays in tests.
 
 ## Governance and license
 
 Fato07 is the initial maintainer. Maintainer approval and passing checks are required to merge. There is no CLA or DCO at this stage.
 
-By contributing, you agree that your contribution is licensed under the repository's MIT License and that you have the right to submit it.
+Contributions are licensed under the repository's MIT License.

package/README.md

@@ -7,251 +7,258 @@
 <p align="center">
   <a href="https://fato07.github.io/codex-grok-mcp/">Website</a> ·
   <a href="https://www.npmjs.com/package/codex-grok-mcp">npm</a> ·
-  <a href="https://github.com/Fato07/codex-grok-mcp/releases/tag/v0.2.0-beta.4">v0.2.0-beta.4</a>
+  <a href="https://github.com/Fato07/codex-grok-mcp/releases/tag/v0.2.0-beta.6">v0.2.0-beta.6</a>
 </p>
 
-An unofficial, local-first MCP bridge that lets Codex ask the authenticated Grok CLI for a bounded second opinion. Its experimental paired bridge can also read bounded status and sanitized recent text from, or message, an exact persistent Grok Bot without exporting Grok Bot's gateway credential.
+An unofficial, local-first bridge that lets Codex ask Grok once or collaborate with named Grok Bots already running inside the Grok Bot app.
 
 > [!IMPORTANT]
-> Each `grok_ask` call sends the supplied prompt to xAI/Grok and consumes allowance from the signed-in Grok account. Experimental Bot sends are separate external writes. Bot reads expose sensitive transcript text to Codex as untrusted external content. This project is not affiliated with or endorsed by OpenAI or xAI.
+> `grok_ask` sends your prompt to xAI and consumes allowance from the signed-in Grok account. Persistent Bot reads may contain sensitive, untrusted text. Bot messages are external writes and are never retried automatically. This project is not affiliated with or endorsed by OpenAI or xAI.
 
-The public beta is distributed as the exact npm package `codex-grok-mcp@0.2.0-beta.4` and an immutable GitHub prerelease.
+## Status
 
-## What it is
-
-```text
-Codex -> local MCP server -> isolated Grok CLI -> xAI
-                           -> authenticated encrypted relay <- companion in Grok Bot VM
-                                                    -> local gateway -> named Bots
-```
-
-The default connector exposes `grok_ask` plus the read-only `grok_bridge_status`. The ask tool pins a Grok model, runs one turn without subagents, and always disables Grok web search. Status returns only local mode/version metadata until the bridge is paired.
-
-`grok_ask` talks to **Grok CLI**, not a persistent named **Grok Bot**. It cannot enter a Bot conversation, use Bot memory, read Bot transcripts, or control the Grok Bot desktop app.
+| Capability | Current status |
+|---|---|
+| Isolated Grok CLI call | Public beta; live-tested on macOS |
+| Persistent Grok Bot collaboration: list, read, wait, and exact-ID send | Experimental; live operator smoke test passed |
+| Companion lifecycle | Managed beta candidate; Linux CI passed, live Grok Bot VM validation pending |
+| Linux isolated CLI path | Unverified |
+| Windows, WSL, and Codex cloud | Unsupported or unverified |
 
-After pairing, the server additionally exposes `grok_list_bots`, `grok_read_bot`, `grok_wait_for_bot`, `grok_send_bot_message`, and `grok_ping_all_bots`. `grok_bridge_status` then performs an authenticated metadata-only handshake that returns connector and companion versions, supported bridge capabilities, gateway health/busy state, and the non-group Bot count—never Bot identities, relay details, credentials, or content. Codex and the VM companion initiate outbound WebSocket connections to an opaque relay. A bearer derived for one random channel blocks anonymous or cross-channel relay allocation, while AES-256-GCM encrypts application frames end to end. The relay sees connection metadata, a random channel, and roles, but not Bot IDs, names, or messages. The Grok gateway token remains inside the managed VM.
+The supported public beta is the exact npm package `codex-grok-mcp@0.2.0-beta.6` and its immutable GitHub prerelease.
 
-The VM companion implements only local discovery, health, roster listing, exact-ID bounded text/status reads, and exact-ID send. Each bridge operation pins one verified local gateway descriptor and token, so an exact-ID roster check and its subsequent read or send cannot cross a gateway restart. Its unofficial gateway contract was cross-checked against the MIT-licensed [`grokbot-sdk`](https://github.com/Adam91holt/grokbot-sdk), but the Node-22-only SDK is not a runtime dependency because the live Grok Bot VM currently provides Node.js 20. Group rooms are excluded from the Bot roster and fail closed on reads. A live metadata-only probe has verified local gateway discovery and full-roster access inside a Grok Bot VM; paired reads and sends remain experimental and may break when Grok Bot changes.
+## Quick start
 
-## Five-minute local install
+You need:
 
-Prerequisites:
+- macOS;
+- Node.js 20.19.2 or newer;
+- Codex CLI or desktop.
 
-- macOS; this is the only platform verified for the isolated CLI path in this beta.
-- Node.js 20.19.2 or newer.
-- Codex CLI/desktop.
-- Grok CLI installed and signed in. Confirm with `grok --version` and `grok models`.
+For one-off `grok_ask` calls, install and sign in to Grok CLI (`grok --version` and `grok models`). Persistent Bot collaboration instead uses Grok Bot and the companion setup below.
 
-Install the repository marketplace at the immutable beta tag, then install the plugin:
+Install the immutable marketplace release and plugin:
 
 ```bash
-codex plugin marketplace add Fato07/codex-grok-mcp --ref v0.2.0-beta.4
+codex plugin marketplace add Fato07/codex-grok-mcp --ref v0.2.0-beta.6
 codex plugin add codex-grok-mcp@codex-grok
 ```
 
-Start a new Codex task so it discovers the plugin, then try:
+Start a new Codex task, then try:
 
 ```text
 Ask Grok to challenge this architecture and return the three strongest objections.
 ```
 
-The plugin uses `npx` to run only `codex-grok-mcp@0.2.0-beta.4`. It does not modify Grok authentication.
+That uses the one-off path. To work with Bots already running in Grok Bot, complete [the persistent Bot setup](#connect-codex-to-grok-bots).
 
-## Direct Codex MCP setup
+The plugin runs only `codex-grok-mcp@0.2.0-beta.6` through `npx`. It does not change Grok authentication.
 
-If you do not want the plugin wrapper:
+For direct MCP setup without the plugin wrapper:
 
 ```bash
-codex mcp add grok -- npx --yes --package=codex-grok-mcp@0.2.0-beta.4 -- codex-grok-mcp
+codex mcp add grok -- npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- codex-grok-mcp
 ```
 
-Start a new Codex task after adding the server, then ask Codex to use `grok_ask`.
+Start a new Codex task after adding the server.
 
-## Doctor
-
-Run after the local package installation:
+## Check setup
 
 ```bash
-npx --yes --package=codex-grok-mcp@0.2.0-beta.4 -- codex-grok-mcp --doctor
+npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- codex-grok-mcp --doctor
 ```
 
-Doctor checks local prerequisites and configuration without sending a prompt to Grok. It must not print authentication material.
-
-## Pair persistent Grok Bots
+Doctor checks the local executable, login, and selected model without sending a prompt. It must not print authentication material.
 
-The repository contains a small Cloudflare Durable Object relay in [`relay/`](relay/). It forwards opaque frames, stores no messages or credentials, hibernates while idle, and is not deployed automatically.
+## Two ways to use it
 
-Deploy your own relay, then pair Codex on the Mac. The same random master token must be set in Cloudflare and supplied once to the local pairing command. Pairing derives a channel-only bearer for both clients; the deployment master is not copied into the pair code or Grok VM, and neither credential appears in a relay URL.
-
-```bash
-cd relay
-npm ci
-RELAY_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
-printf 'RELAY_ACCESS_TOKEN=%s\n' "$RELAY_TOKEN" | npx wrangler deploy --secrets-file /dev/stdin
-
-cd ..
-CODEX_GROK_RELAY_TOKEN="$RELAY_TOKEN" npx --yes --package=codex-grok-mcp@0.2.0-beta.4 -- codex-grok-mcp pair --relay-url wss://YOUR-WORKER.workers.dev/v1/connect
-unset RELAY_TOKEN
+```text
+Codex -> local MCP server -> isolated Grok CLI -> xAI
+                           -> encrypted relay <- companion in Grok Bot VM
+                                                -> loopback gateway -> named Bots
 ```
 
-The pairing command requires an interactive terminal and prints the credential only there. Keep it private. In **Grok Bot's Computer** terminal—not in a Bot chat—run the exact companion release and paste the code into the no-echo prompt:
-
-```bash
-npx --yes --package=codex-grok-mcp@0.2.0-beta.4 -- codex-grok-bridge probe
-npx --yes --package=codex-grok-mcp@0.2.0-beta.4 -- codex-grok-bridge connect
-```
+`grok_ask` starts one constrained Grok CLI turn with a private temporary home. It cannot enter a persistent Bot conversation, use Bot memory, read files, run commands, use subagents, or search the web.
 
-To update an already paired companion, stop the foreground process with `Ctrl-C`, then run the exact package version with `run`; pairing again is unnecessary:
+Each call may select one supported model. Omit `model` to use `GROK_MCP_MODEL`; provider, base URL, endpoint, and persistent Bot model settings are not accepted.
 
-```bash
-npx --yes --package=codex-grok-mcp@0.2.0-beta.4 -- codex-grok-bridge probe
-npx --yes --package=codex-grok-mcp@0.2.0-beta.4 -- codex-grok-bridge run
-```
+The persistent path is the collaborative mode. Codex can list named non-group Bots running inside Grok Bot, inspect one, send it a task once, wait for its activity state, and read its latest bounded messages. Codex can then continue its own work using that update while the Bot's ongoing conversation stays in Grok Bot.
 
-Operators who deliberately prefer automatic beta updates on each companion restart can use the npm beta channel:
+This creates a practical `send -> wait -> read -> continue` loop. The bridge does not claim that a message answers a specific send or that an idle Bot completed its task.
 
-```bash
-SAND_DATA_ROOT=/home/box/sand-data npx --yes --prefer-online --package=codex-grok-mcp@beta -- codex-grok-bridge run
-```
+The gateway token stays inside the Grok Bot VM. Codex and the companion connect outward to a self-hosted relay. Application frames are encrypted end to end; the relay forwards ciphertext and stores no messages.
 
-The mutable channel never edits pairing state or hot-swaps a running companion. It trades reproducibility for convenience; the plugin and security-sensitive deployments should keep using an exact audited version. To roll back, stop the companion and run a previously verified exact version. Never run a mutable GitHub branch inside the credential-bearing VM.
+## Architecture
 
-`probe` returns only gateway health, process metadata, Bot count, and a roster fingerprint. It never prints the gateway token, URL, Bot names, IDs, transcripts, or prompts.
+[![Codex enters one local MCP server, then uses either an isolated Grok CLI call or an encrypted relay to named Grok Bots.](docs/assets/architecture-overview.png)](https://fato07.github.io/codex-grok-mcp/architecture.html)
 
-The source beta companion currently runs in the foreground. Keep that terminal running while using the Bot tools. Background survival across Grok VM idle periods and computer updates is not yet claimed. The replay ledger survives restarts under `${XDG_STATE_HOME}/codex-grok-mcp/replay` when `XDG_STATE_HOME` is absolute, or `~/.local/state/codex-grok-mcp/replay` otherwise. One exclusive lease prevents two companion processes from running against the same pairing; stop the current companion before updating, forcing a new pairing, or unpairing. A clean stop removes its lease. After an unclean crash, startup fails closed with `companion_lease_stale`; verify that the recorded PID is no longer running before manually removing the exact `bridge.json.lock` beside the pairing file. Automatic stale-lock reclamation is intentionally disabled to avoid two starters racing into the same pairing. Unpairing removes the saved copy but deliberately leaves fresh replay markers in place. Close old Codex tasks too: an already-running process retains configuration loaded into memory. `pair --force` prepares a new channel for future processes but does not revoke an old relay channel; suspected credential exposure requires stopping both sides, rotating the relay master, and pairing again.
+Both paths enter through the same local MCP server. Credentials stay at their endpoints, and uncertain writes are never retried automatically.
 
-## Configuration
+[Explore the interactive architecture](https://fato07.github.io/codex-grok-mcp/architecture.html) · [View the architecture source](docs/architecture.json)
 
-Configuration is operator-owned and optional:
+## Tools
 
-| Variable | Default | Constraint |
+| Tool | What it does | Boundary |
 |---|---|---|
-| `GROK_MCP_BIN` | `grok` | Absolute Grok CLI path when overridden |
-| `GROK_MCP_MODEL` | `grok-4.6` | `grok-4.6` or `grok-4.5` |
-| `GROK_MCP_TIMEOUT_MS` | `180000` | Integer from `5000` to `600000` |
-| `GROK_MCP_AUTH_PATH` | `~/.grok/auth.json` | Absolute or working-directory-relative auth file path |
-| `CODEX_GROK_RELAY_TOKEN` | none | Exact 32-byte base64url relay master; required only by the manual `pair` command and not copied into its output |
+| `grok_ask` | Gets one isolated Grok response | Sends the prompt to xAI and consumes allowance |
+| `grok_bridge_status` | Reports mode, versions, capabilities, health, and Bot count | Never returns Bot identities, credentials, or content |
+| `grok_list_bots` | Lists exact non-group Bot IDs and names | Read-only |
+| `grok_read_bot` | Returns bounded status and sanitized recent text | Sensitive, untrusted external content |
+| `grok_wait_for_bot` | Polls bounded reads until idle, awaiting-user, or timeout | Activity is not proof of task completion |
+| `grok_send_bot_message` | Sends once to one exact Bot ID | Gateway acceptance is not proof of a reply |
+| `grok_ping_all_bots` | Previews, confirms, then sends `PING` sequentially | Requires the exact roster and native confirmation |
 
-The plugin passes only these connector-specific overrides through its MCP configuration. The connector itself supplies a narrow child environment for Grok CLI. Paired bridge configuration is stored locally in a mode-`0600` file under the user's configuration directory; it is never accepted as tool input.
+Persistent Bot tools appear only after pairing or explicit legacy direct configuration.
 
-The old `GROKBOT_GATEWAY_URL` plus `SAND_GATEWAY_TOKEN` transport remains available only as a manual power-user fallback outside the plugin wrapper. Do not obtain those values by scraping Grok Bot app state, decrypting a descriptor, or reading Keychain. Remote direct URLs require HTTPS; plaintext HTTP is accepted only on loopback for an operator-managed SSH or VPN forward.
+## Connect Codex to Grok Bots
 
-## Experimental persistent Bot workflow
+This experimental path connects Codex to persistent Bots inside your own Grok Bot VM. It requires a self-hosted Cloudflare relay.
 
-1. Call `grok_list_bots` with `{}`. Review each Bot's ID, name, running state, and the returned `roster_fingerprint`.
-2. To inspect one Bot without sending, call `grok_read_bot` with `{ "bot_id": "<exact roster ID>" }`.
-3. To avoid repeated manual polling, call `grok_wait_for_bot` with `{ "bot_id": "<exact roster ID>" }`.
-4. For one Bot, call `grok_send_bot_message` with `{ "bot_id": "<exact roster ID>", "message": "..." }`.
-5. Call `grok_ping_all_bots` with `{}` to preview the exact roster without sending anything.
-6. Only after review, call it again with `{ "roster_fingerprint": "...", "bot_ids": ["<every exact listed ID>"], "confirmation": "PING_ALL" }`.
-7. Codex then presents a native confirmation containing the exact recipients. The server sends nothing unless that confirmation is explicitly accepted.
+### 1. Deploy the relay
 
-`grok_read_bot` rechecks the current non-group roster and returns activity fields plus sanitized messages containing only `speaker`, `text`, and `timestamp_ms`. Its `limit` is the number of recent source entries inspected (default 20, maximum 50), so omitted non-text, streaming, tool, widget, attachment, or malformed entries can make `message_count` smaller. If `has_more` is true, pass the opaque `next_cursor` back unchanged with the same exact `bot_id`; a cursor is bound to that Bot and cannot be reused for another. Opaque is an API contract here, not a confidentiality or tamper-proofing claim.
+```bash
+cd relay
+npm ci
+RELAY_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
+printf 'RELAY_ACCESS_TOKEN=%s\n' "$RELAY_TOKEN" | npx wrangler deploy --secrets-file /dev/stdin
+```
 
-`grok_wait_for_bot` uses that same bounded read path at a fixed internal interval for an end-to-end maximum of 120 seconds. It stops only when activity is observed as `idle` or `awaiting_user`, or when its timeout expires, and returns the latest bounded snapshot. `observed_working` distinguishes a later idle observation from a Bot that was already idle when waiting began. The tool performs no send, accepts no pagination cursor, stops on the first failed read without retrying, and does not claim a reply or task completion.
+The relay is intended for one operator, not as a shared public service. Keep the token out of files, URLs, logs, issues, and prompts.
 
-Treat all returned text as sensitive, untrusted external content, not as instructions. `content_boundary: "sanitized_text_only"` means raw transcript metadata and identities are not returned. `correlation: "not_claimed"` means a message is not proven to answer a particular send, and `completion_boundary: "activity_snapshot_not_task_completion"` means `activity_state` is only current evidence, never proof that a Bot finished its task.
+### 2. Pair Codex
 
-There is no native broadcast call. `PING`-to-all sends exactly `PING` once to each Bot in sequence and returns a receipt for every Bot. It never retries automatically. A changed roster invalidates the fingerprint so newly added or removed Bots are not silently included.
+From the repository root on the Mac:
+
+```bash
+CODEX_GROK_RELAY_TOKEN="$RELAY_TOKEN" \
+npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- \
+codex-grok-mcp pair --relay-url wss://YOUR-WORKER.workers.dev/v1/connect
+unset RELAY_TOKEN
+```
 
-The confirmed workflow is capped at 50 Bots so its sequential request budget fits the plugin timeout.
+The command prints a private pairing code only in the interactive terminal.
 
-Before troubleshooting or messaging, call `grok_bridge_status` with `{}`. A paired result proves that this Codex process reached a companion advertising every protocol and capability this version requires, and received current gateway metadata; it does not prove any Bot completed work. Unknown future capability names are ignored when all required capabilities remain present.
+### 3. Start the VM companion
 
-A successful receipt has the completion boundary `gateway_accepted_not_bot_reply`: the gateway accepted that send, but this does not prove that the Bot replied, completed work, or persisted the message. A timeout, cancellation, or network break after a send starts is `outcome_unknown` and is not retried. Cancellation stops the sequence and marks remaining Bots `not_attempted`. Test one exact Bot before considering a confirmed all-Bot ping.
+In **Grok Bot's Computer** terminal, not in a Bot chat, run:
 
-## Privacy and isolation boundary
+```bash
+npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- codex-grok-bridge probe
+npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- codex-grok-bridge connect
+```
 
-Every `grok_ask` call deliberately crosses an external data boundary: the prompt goes from Codex to xAI through Grok CLI. Do not send secrets, credentials, private source, personal data, or regulated data unless you are authorized to share it with xAI.
+Paste the pairing code into the no-echo prompt. Keep the terminal running while using Bot tools.
 
-The Grok child process runs with private temporary `HOME` and `GROK_HOME` directories. Only the existing authentication file—`~/.grok/auth.json` by default—is symlinked into the isolated `GROK_HOME`; the connector checks the file but does not read it. The rest of the user's `~/.grok` state—sessions, memory, plugins, logs, configuration, and Bot data—is not mounted into the child home. The connector removes its prompt file and temporary home after each call.
+### Update or roll back
 
-This boundary limits what the Grok child discovers by default. It is not a general sandbox for the Codex process or this Node.js MCP server. The paired Bot bridge is a separate network and credential boundary; it does not weaken or reuse the isolated `grok_ask` runner.
+Stop the foreground companion with `Ctrl-C`, then run the chosen exact version:
 
-The connector does not intentionally log prompt, response, or Bot transcript content, child arguments, stdout/stderr, environment values, authentication data, or temporary paths. Safe operational fields may include the connector version, elapsed time, prompt byte count, a request identifier, and a coarse exit category.
+```bash
+npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- codex-grok-bridge probe
+npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- codex-grok-bridge run
+```
 
-## Compatibility
+For automatic beta updates on each restart, with the reproducibility tradeoff made explicit:
 
-| Environment | Status |
-|---|---|
-| macOS, current local Codex and Grok CLI | Verified target for `0.2.0-beta.4` isolated CLI path |
-| Linux | Planned; unverified |
-| Windows / WSL | Unverified |
-| Codex cloud | Unsupported; the connector needs a local Grok executable and login |
-| Grok Bot VM gateway discovery and roster probe | Verified metadata-only on Node.js 20.19.2 |
-| Paired bounded Bot reads | Experimental; live operator smoke test passed on the current private beta |
-| Paired exact-ID Bot messaging | Experimental; gateway acceptance and later bounded transcript observation passed in a live operator smoke test |
-| Background companion lifecycle | Unsupported; foreground operation only |
+```bash
+SAND_DATA_ROOT=/home/box/sand-data \
+npx --yes --prefer-online --package=codex-grok-mcp@beta -- codex-grok-bridge run
+```
 
-Passing unit tests is not compatibility proof. A platform becomes supported only after a live model-identity smoke test.
+This mutable command never edits pairing state or updates a running process. Prefer exact versions for audited or unattended environments. Roll back by stopping the companion and running a previously verified version.
 
-## Troubleshooting
+### Managed lifecycle beta
 
-### `codex-grok-mcp` is not found
+`0.2.0-beta.6` introduces managed lifecycle commands. Linux CI covers the detached process path, while public support remains pending the redacted live Grok Bot VM gate.
 
-Run the pinned package doctor directly:
+After pairing, stop the old foreground companion once. Then install and start an exact lifecycle-capable release:
 
 ```bash
-npx --yes --package=codex-grok-mcp@0.2.0-beta.4 -- codex-grok-mcp --doctor
+VERSION=<exact-version>
+npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge install
 ```
 
-### Grok CLI is missing or not signed in
-
-Run:
+`status`, `start`, `stop`, and `ensure` are idempotent. `restart` intentionally performs a fresh cycle:
 
 ```bash
-grok --version
-grok models
+npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge status
+npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge start
+npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge stop
+npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge restart
+npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge ensure
 ```
 
-Complete Grok's normal login flow outside Codex, then rerun doctor. This connector never asks Codex for tokens or passwords.
+An exact update stages and checks the replacement before the healthy process stops. The prior exact release stays available for one retry-safe rollback:
+
+```bash
+NEXT_VERSION=<new-exact-version>
+npx --yes --package "codex-grok-mcp@${NEXT_VERSION}" -- codex-grok-bridge update
+npx --yes --package "codex-grok-mcp@${NEXT_VERSION}" -- codex-grok-bridge rollback
+```
 
-### The requested Grok model is unavailable
+The rollback operation uses the retained release, and a repeated rollback is a no-op. Pairing is read and revalidated, never rewritten. For VM resume recovery, a Grok Bot routine may run the exact pinned `ensure` command. Routine creation remains an explicit operator action.
 
-Use `grok models` to inspect what the signed-in account can access. The connector fails closed instead of silently using the Grok CLI default, because that default may not be a Grok model.
+To opt into the mutable beta channel for one update, make the channel visible in that command:
 
-### The request times out or allowance is exhausted
+```bash
+npx --yes --prefer-online --package=codex-grok-mcp@beta -- codex-grok-bridge update
+```
 
-Retry only after checking the Grok account and direct CLI behavior. A retry consumes another request if the first one reached xAI.
+The resolved release is stored as an exact version. Later `start`, `restart`, `ensure`, and `rollback` operations do not resolve a mutable channel.
 
-### Codex does not show the tool
+## Collaborating safely with persistent Bots
 
-Run `codex plugin marketplace list`, confirm the `codex-grok` Git marketplace, reinstall the plugin, and start a new task. For direct setup, inspect `codex mcp list`.
+1. Call `grok_bridge_status`, then use `grok_list_bots` to choose one exact Bot ID.
+2. Use `grok_read_bot` or `grok_wait_for_bot` for read-only inspection.
+3. Use `grok_send_bot_message` once for one exact target.
+4. For all-Bot `PING`, preview the roster and review the native confirmation before accepting it.
 
-### Direct CLI works but the connector fails
+Reads return sanitized text only. Attachments and other non-text transcript entries are omitted. Reads do not prove that a message answered a particular send or that a task finished. A successful send receipt means only that the gateway accepted the request. Timeouts and interrupted sends remain `outcome_unknown`; do not retry them automatically.
 
-Run the pinned package doctor, record the connector, Node, Codex, Grok CLI, OS, and architecture versions, and report a bug with redacted output. Never attach `~/.grok/auth.json`, prompts, responses, or transcripts.
+## Configuration
 
-### Experimental Bot tools do not appear
+| Variable | Default | Rule |
+|---|---|---|
+| `GROK_MCP_BIN` | `grok` | Override with an absolute path |
+| `GROK_MCP_MODEL` | `grok-4.6` | `grok-4.6` or `grok-4.5` |
+| `GROK_MCP_TIMEOUT_MS` | `180000` | Integer from `5000` to `600000` |
+| `GROK_MCP_AUTH_PATH` | `~/.grok/auth.json` | Operator-owned auth file |
+| `CODEX_GROK_RELAY_TOKEN` | none | Required only by the local `pair` command |
 
-Confirm `RELAY_ACCESS_TOKEN` is set on the relay, run the pinned `codex-grok-mcp pair` command with the same value in `CODEX_GROK_RELAY_TOKEN`, keep the pinned `codex-grok-bridge connect` command running in Grok Bot's Computer, and start a new Codex task. Never paste the pairing code or gateway token into a Bot/Codex prompt or issue.
+The plugin passes only these connector options. Pairing is stored in a private mode-`0600` local file and is never accepted as MCP tool input.
 
-If `grok_bridge_status` or `grok_read_bot` returns `UPGRADE_REQUIRED`, update and restart the VM companion. Status uses bridge protocol v3, reads use v2, and roster listing plus sends remain compatible with v1.
+## Troubleshooting
 
-### `probe` returns `DATA_ROOT_SYMLINK`
+- **Tool missing:** confirm the `codex-grok` marketplace and plugin are installed, then start a new Codex task. For direct setup, inspect `codex mcp list`.
+- **CLI missing or signed out:** run `grok --version`, `grok models`, and the pinned doctor command. Complete normal Grok login outside Codex.
+- **`UPGRADE_REQUIRED`:** stop and restart the VM companion with the same package version as the connector.
+- **`DATA_ROOT_SYMLINK`:** set `SAND_DATA_ROOT` to the real Grok Bot data directory, not a symlink. The companion rejects symlinked descriptor parents.
+- **`companion_lease_stale`:** a lifecycle-capable managed install can run the exact pinned `ensure` command, which clears only a revalidated dead managed lease. For a foreground install, verify the recorded PID is gone before removing only the adjacent `bridge.json.lock`.
+- **Uncertain send:** inspect the Bot before considering any new action. A retry may duplicate a message.
 
-Point `SAND_DATA_ROOT` at the real Grok Bot data directory rather than a symlink, then rerun the pinned `probe` command. The companion rejects symlinked descriptor parents to prevent gateway credential substitution; it reports only the safe reason and never the path.
+When reporting a bug, include redacted OS, architecture, Node, Codex, Grok CLI, and connector versions. Never attach authentication files, pairing codes, gateway/relay tokens, prompts, responses, transcripts, or private paths.
 
 ## Uninstall
 
-If installed as a plugin, uninstall **Codex Grok MCP** in the Codex desktop app, then remove the local marketplace:
+1. Stop the VM companion. Press `Ctrl-C` for a foreground process. For a managed beta.6 install, run:
 
-```bash
-codex plugin marketplace remove codex-grok
-```
+   ```bash
+   npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- codex-grok-bridge stop
+   ```
 
-If configured directly, remove that MCP entry too:
+2. In the VM terminal, remove its pairing:
 
-```bash
-codex mcp remove grok
-```
+   ```bash
+   npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- codex-grok-bridge unpair
+   ```
 
-Remove both pairing files before uninstalling:
+3. On the Mac, remove the local pairing:
 
-```bash
-npx --yes --package=codex-grok-mcp@0.2.0-beta.4 -- codex-grok-mcp unpair
-npx --yes --package=codex-grok-mcp@0.2.0-beta.4 -- codex-grok-bridge unpair
-```
+   ```bash
+   npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- codex-grok-mcp unpair
+   ```
+
+4. Uninstall **Codex Grok MCP** in Codex. If configured directly, run `codex mcp remove grok`. Then remove the marketplace with `codex plugin marketplace remove codex-grok`.
 
 Uninstalling does not change or delete Grok CLI authentication or account data.
 
@@ -260,12 +267,13 @@ Uninstalling does not change or delete Grok CLI authentication or account data.
 ```bash
 npm ci
 npm ci --prefix relay
-npm run typecheck
 npm run test:all
+npm audit --omit=dev
+npm audit --prefix relay
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before opening a change.
 
 ## License and attribution
 
-MIT. The process-runner design was informed by the MIT-licensed [`libraz/grok-mcp`](https://github.com/libraz/grok-mcp). The bounded Grok Bot gateway contract was cross-checked against the MIT-licensed [`Adam91holt/grokbot-sdk`](https://github.com/Adam91holt/grokbot-sdk). See repository history and accompanying notices for exact reused or adapted code if applicable.
+MIT. The process-runner design was informed by the MIT-licensed [`libraz/grok-mcp`](https://github.com/libraz/grok-mcp). The bounded Grok Bot gateway contract was cross-checked against the MIT-licensed [`Adam91holt/grokbot-sdk`](https://github.com/Adam91holt/grokbot-sdk).