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

package/CONTRIBUTING.md

@@ -4,7 +4,8 @@ Thanks for helping keep this bridge small, safe, and dependable.
 
 ## Before opening a change
 
-- Open an issue or discussion before adding a tool, adapter, dependency, authentication path, or supported platform.
+- 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.
@@ -41,6 +42,8 @@ npm pack --dry-run
 
 Do not add postinstall scripts or telemetry. Version changes belong in release work, not ordinary feature pull requests.
 
+For a stable release candidate, use the single maintainer checklist in [RELEASING.md](RELEASING.md).
+
 ## Compatibility claims
 
 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.

package/README.md

@@ -7,7 +7,7 @@
 <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.5">v0.2.0-beta.5</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 bridge that lets Codex ask Grok once or collaborate with named Grok Bots already running inside the Grok Bot app.
@@ -21,11 +21,11 @@ An unofficial, local-first bridge that lets Codex ask Grok once or collaborate w
 |---|---|
 | 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 | Foreground process only |
+| 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 |
 
-The supported public beta is the exact npm package `codex-grok-mcp@0.2.0-beta.5` and its immutable GitHub prerelease.
+The supported public beta is the exact npm package `codex-grok-mcp@0.2.0-beta.6` and its immutable GitHub prerelease.
 
 ## Quick start
 
@@ -33,13 +33,14 @@ You need:
 
 - macOS;
 - Node.js 20.19.2 or newer;
-- Codex CLI or desktop;
-- Grok CLI installed and signed in (`grok --version` and `grok models`).
+- Codex CLI or desktop.
+
+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 immutable marketplace release and plugin:
 
 ```bash
-codex plugin marketplace add Fato07/codex-grok-mcp --ref v0.2.0-beta.5
+codex plugin marketplace add Fato07/codex-grok-mcp --ref v0.2.0-beta.6
 codex plugin add codex-grok-mcp@codex-grok
 ```
 
@@ -51,12 +52,12 @@ Ask Grok to challenge this architecture and return the three strongest objection
 
 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).
 
-The plugin runs only `codex-grok-mcp@0.2.0-beta.5` through `npx`. It does not change Grok authentication.
+The plugin runs only `codex-grok-mcp@0.2.0-beta.6` through `npx`. It does not change Grok authentication.
 
 For direct MCP setup without the plugin wrapper:
 
 ```bash
-codex mcp add grok -- npx --yes --package=codex-grok-mcp@0.2.0-beta.5 -- 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.
@@ -64,7 +65,7 @@ Start a new Codex task after adding the server.
 ## Check setup
 
 ```bash
-npx --yes --package=codex-grok-mcp@0.2.0-beta.5 -- codex-grok-mcp --doctor
+npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- codex-grok-mcp --doctor
 ```
 
 Doctor checks the local executable, login, and selected model without sending a prompt. It must not print authentication material.
@@ -79,13 +80,21 @@ Codex -> local MCP server -> isolated Grok CLI -> xAI
 
 `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.
 
+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.
+
 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.
 
 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.
 
 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.
 
-[Explore the full architecture](https://fato07.github.io/codex-grok-mcp/architecture.html).
+## Architecture
+
+[![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)
+
+Both paths enter through the same local MCP server. Credentials stay at their endpoints, and uncertain writes are never retried automatically.
+
+[Explore the interactive architecture](https://fato07.github.io/codex-grok-mcp/architecture.html) · [View the architecture source](docs/architecture.json)
 
 ## Tools
 
@@ -122,7 +131,7 @@ From the repository root on the Mac:
 
 ```bash
 CODEX_GROK_RELAY_TOKEN="$RELAY_TOKEN" \
-npx --yes --package=codex-grok-mcp@0.2.0-beta.5 -- \
+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
 ```
@@ -134,8 +143,8 @@ The command prints a private pairing code only in the interactive terminal.
 In **Grok Bot's Computer** terminal, not in a Bot chat, run:
 
 ```bash
-npx --yes --package=codex-grok-mcp@0.2.0-beta.5 -- codex-grok-bridge probe
-npx --yes --package=codex-grok-mcp@0.2.0-beta.5 -- codex-grok-bridge connect
+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
 ```
 
 Paste the pairing code into the no-echo prompt. Keep the terminal running while using Bot tools.
@@ -145,8 +154,8 @@ Paste the pairing code into the no-echo prompt. Keep the terminal running while
 Stop the foreground companion with `Ctrl-C`, then run the chosen exact version:
 
 ```bash
-npx --yes --package=codex-grok-mcp@0.2.0-beta.5 -- codex-grok-bridge probe
-npx --yes --package=codex-grok-mcp@0.2.0-beta.5 -- codex-grok-bridge run
+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
 ```
 
 For automatic beta updates on each restart, with the reproducibility tradeoff made explicit:
@@ -158,6 +167,45 @@ npx --yes --prefer-online --package=codex-grok-mcp@beta -- codex-grok-bridge run
 
 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.
 
+### Managed lifecycle beta
+
+`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.
+
+After pairing, stop the old foreground companion once. Then install and start an exact lifecycle-capable release:
+
+```bash
+VERSION=<exact-version>
+npx --yes --package "codex-grok-mcp@${VERSION}" -- codex-grok-bridge install
+```
+
+`status`, `start`, `stop`, and `ensure` are idempotent. `restart` intentionally performs a fresh cycle:
+
+```bash
+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
+```
+
+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 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.
+
+To opt into the mutable beta channel for one update, make the channel visible in that command:
+
+```bash
+npx --yes --prefer-online --package=codex-grok-mcp@beta -- codex-grok-bridge update
+```
+
+The resolved release is stored as an exact version. Later `start`, `restart`, `ensure`, and `rollback` operations do not resolve a mutable channel.
+
 ## Collaborating safely with persistent Bots
 
 1. Call `grok_bridge_status`, then use `grok_list_bots` to choose one exact Bot ID.
@@ -165,7 +213,7 @@ This mutable command never edits pairing state or updates a running process. Pre
 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.
 
-Reads return sanitized text only. They 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.
+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.
 
 ## Configuration
 
@@ -185,24 +233,29 @@ The plugin passes only these connector options. Pairing is stored in a private m
 - **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`:** verify the recorded PID is no longer running before removing only the adjacent `bridge.json.lock`. Automatic stale-lock removal is intentionally disabled.
+- **`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.
 
 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
 
-1. Stop the foreground companion.
+1. Stop the VM companion. Press `Ctrl-C` for a foreground process. For a managed beta.6 install, run:
+
+   ```bash
+   npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- codex-grok-bridge stop
+   ```
+
 2. In the VM terminal, remove its pairing:
 
    ```bash
-   npx --yes --package=codex-grok-mcp@0.2.0-beta.5 -- codex-grok-bridge unpair
+   npx --yes --package=codex-grok-mcp@0.2.0-beta.6 -- codex-grok-bridge unpair
    ```
 
 3. On the Mac, remove the local pairing:
 
    ```bash
-   npx --yes --package=codex-grok-mcp@0.2.0-beta.5 -- codex-grok-mcp unpair
+   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`.

package/RELEASING.md

@@ -0,0 +1,127 @@
+# v0.2.0 stable release gate
+
+This is the sole maintainer checklist for promoting `codex-grok-mcp` from beta to stable. The default decision is **NO-SHIP** until every required item passes.
+
+Run the checklist from a clean checkout of the final candidate commit. Every proof must name and come from that same 40-character commit SHA. Any source, test, lockfile, metadata, workflow, or documentation change creates a new candidate and invalidates earlier proof. Earlier beta results are context, not acceptance evidence.
+
+Copy this file outside the candidate checkout to record results and evidence links. Never edit the candidate checkout while testing, because that would create a different candidate.
+
+## Candidate identity
+
+Record one immutable identity before testing:
+
+| Field | Required value |
+|---|---|
+| Package | `codex-grok-mcp@0.2.0` |
+| Intended Git tag | `v0.2.0` |
+| Final candidate commit | `<40-character SHA>` |
+| Packed artifact | `codex-grok-mcp-0.2.0.tgz` |
+| Artifact integrity | `<integrity from npm pack --json>` |
+| Rollback package | `codex-grok-mcp@<previous verified exact version>` |
+| Evidence record | `<durable URL>` |
+
+- [ ] The checkout is clean and `HEAD` equals the recorded candidate commit.
+- [ ] Package metadata, lockfiles, source version, plugin metadata, launcher pin, public documentation, packed manifest, and intended tag all identify `0.2.0`.
+- [ ] The packed artifact was built from the recorded commit outside the checkout and matches the recorded SHA-512.
+- [ ] Every live candidate install uses that artifact and verifies its SHA-512 first. No command uses `@beta`, `@latest`, or an unpinned branch.
+
+## Required dependencies
+
+Each dependency must be complete, included where applicable in the final candidate, and linked from the evidence record.
+
+- [ ] [#4, one-command companion lifecycle and safe upgrade](https://github.com/Fato07/codex-grok-mcp/issues/4): exact-version install, status, update, restart, and rollback preserve pairing and recover the prior version after failure.
+- [ ] [#5, clean install, upgrade, rollback, and uninstall](https://github.com/Fato07/codex-grok-mcp/issues/5): a clean Codex host and Grok Bot VM pass the full lifecycle with redacted receipts.
+- [ ] [#6, reconnect, restart, and gateway-rotation soak](https://github.com/Fato07/codex-grok-mcp/issues/6): recovery is bounded, post-dispatch ambiguity remains `outcome_unknown`, and sends are not retried.
+- [ ] [#7, invalid-pairing diagnostics](https://github.com/Fato07/codex-grok-mcp/issues/7): wrong-key failures are distinct from `UPGRADE_REQUIRED`, sanitized, and covered by the full suites.
+- [ ] [#8, protected main and required CI](https://github.com/Fato07/codex-grok-mcp/issues/8): a test pull request proves the ruleset requires green CI for the candidate while retaining explicit maintainer recovery.
+- [ ] [#9, release-metadata alignment check](https://github.com/Fato07/codex-grok-mcp/issues/9): the dependency-free check passes and reports exact file and field mismatches when deliberately tested.
+
+## Supported environment
+
+The stable claim is limited to the rows proven below. For `v0.2.0`, the host scope is macOS, Node support starts at `20.19.2`, and automated coverage is Node `20.19.2`, `22`, and `24` on macOS and Ubuntu. Linux is CI evidence only, not live isolated-CLI support. Windows, WSL, and Codex cloud remain unsupported or unverified unless the final candidate adds their own live evidence and updates the public support claim.
+
+| Path | Exact evidence required |
+|---|---|
+| Isolated `grok_ask` | macOS version and architecture; Node, Codex, Grok CLI, connector, and selected Grok model versions; successful doctor and one bounded response |
+| Paired persistent Bots | macOS version and architecture; Grok Bot VM OS or image and architecture; host and VM Node versions; Codex, connector, companion, protocol, and Grok Bot app or host versions; successful lifecycle below |
+
+- [ ] The evidence record contains every version and architecture named in each supported row, using `n/a` only when a component is not part of that path.
+- [ ] Public support text matches only the live-proven rows and does not turn CI, mocks, or an earlier beta run into platform support.
+
+## Automated candidate checks
+
+Run from the clean candidate checkout and link the candidate-specific CI run or redacted log.
+
+Ordinary pull-request and `main` CI stays deterministic and does not call npm's network-dependent audit service. Before tagging, manually dispatch the CI workflow against the exact candidate ref; audits run fail-closed on its Node 24 Ubuntu job. `v*` tag runs execute the same audit gate again.
+
+- [ ] `npm ci` and `npm ci --prefix relay` complete from the committed lockfiles.
+- [ ] `npm run test:all` passes. This includes the root build and core tests plus relay type checks and tests.
+- [ ] `npm audit --omit=dev` passes.
+- [ ] `npm audit --prefix relay` passes.
+- [ ] `npm pack --dry-run` passes and its file list contains only intended publish content.
+- [ ] `npm pack --json --pack-destination /path/outside/candidate-checkout` creates the one recorded artifact and integrity value without changing the checkout.
+- [ ] The release-metadata alignment check from #9 passes.
+- [ ] Required GitHub CI passes for Node `20.19.2`, `22`, and `24` on both macOS and Ubuntu at the candidate SHA.
+
+## Live candidate checks
+
+Use accounts and data the maintainer is authorized to use. Store only redacted receipts. Use separate clean environments for the two flows.
+
+### Clean candidate flow
+
+- [ ] On a clean host, install the exact candidate, start a fresh Codex task, discover the tools, run doctor, and complete one isolated `grok_ask` call.
+- [ ] On a clean host and VM, create a new pairing without exposing it, then probe and start the exact candidate companion.
+- [ ] From a fresh Codex task, verify status, list, bounded read, bounded wait, and one send to one exact non-group Bot ID with no retry.
+- [ ] Stop and restart the exact candidate, then repeat status plus one read-only operation without pairing again.
+- [ ] Uninstall the exact candidate last, and verify that only connector-owned configuration is removed. Grok authentication, Bot data, and unrelated files remain unchanged.
+
+### Upgrade and rollback flow
+
+- [ ] Starting from the recorded rollback version and a new pairing, exercise one controlled failed update and verify that version remains healthy and recoverable.
+- [ ] Upgrade to the recorded candidate artifact, restart it, and repeat status plus one read-only operation without pairing again.
+- [ ] Complete the #6 soak scenarios for relay reconnect, companion restart, VM idle and resume, gateway descriptor/process/token rotation, read and wait recovery, and one no-retry exact-ID send.
+- [ ] Exercise the #7 wrong-key and valid-legacy cases and observe their distinct sanitized results.
+- [ ] Roll back as specified below.
+
+## Pairing-preserving rollback
+
+1. Pair once on the recorded previous verified exact version.
+2. Verify pairing-file byte identity and private permissions locally on both sides, recording only pass or fail, never the digest, file contents, or private path.
+3. Attempt one controlled failed update before replacement becomes active. Verify the previous version remains healthy and recoverable.
+4. Upgrade using the recorded candidate artifact, verify its SHA-512 and the active connector, companion, and protocol versions, then stop and restart it.
+5. Roll back both sides to the recorded previous exact version. Do not run `pair`, `pair --force`, or `unpair`, and do not delete, replace, or regenerate pairing files.
+6. Verify the previous versions, bridge status, and one read-only operation through the original pairing. Repeat the local byte-identity and permission check.
+
+- [ ] The candidate passed this sequence, the original pairing remained byte-identical and usable, and a failed update left the previous version recoverable.
+
+## Proof levels
+
+Record these separately. Passing one never implies a later level.
+
+| Proof | What it establishes | What it does not establish |
+|---|---|---|
+| Gateway acceptance | The exact-ID send received an accepted gateway receipt | Persistence, a reply, correlation, or completion |
+| Transcript response observed | A later bounded Bot-authored transcript entry was observed | That the entry answers this send |
+| Bot activity observed | A point-in-time activity state was read | Reply correlation or task completion |
+| Task completion verified | A maintainer separately checked explicit task acceptance criteria or an artifact | A claim the bridge derives from acceptance, transcript order, or idle state |
+
+- [ ] The live evidence uses all applicable proof labels and makes no stronger claim than the evidence supports.
+
+## Evidence and redaction
+
+Evidence may contain the candidate SHA, public software versions, OS and architecture, protocol numbers, timestamps, coarse results, CI URLs, and sanitized request identifiers.
+
+- [ ] Before upload, inspect every receipt and remove prompts, responses, transcripts, Bot IDs or names, roster fingerprints, credentials, authentication data, pairing codes or files, channels, keys, tokens, gateway or relay URLs, environment values, private paths, and raw stdout or stderr bodies.
+- [ ] Evidence links are durable, access-appropriate, and identify the candidate SHA and exact check without exposing private data.
+
+## Decision
+
+Select exactly one in the evidence record. A decision records the gate result; tagging, publishing, and changing a dist-tag are separate actions.
+
+- [ ] **SHIP**: every required item above passed for the recorded candidate, all #4 through #9 dependencies are resolved, and no stable-release blocker remains.
+- [ ] **NO-SHIP**: one or more items are unproved, stale, failed, unsafe to disclose, or tied to a different commit. Record the blocker and leave beta and release state unchanged.
+
+- Maintainer: `<name>`
+- Decision time (UTC): `<timestamp>`
+- Candidate commit: `<40-character SHA>`
+- Decision: `<SHIP or NO-SHIP>`

package/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported versions
 
-`0.2.0-beta.5` is the supported public beta. Security fixes target the current source revision and the next prerelease.
+`0.2.0-beta.6` is the supported public beta. Security fixes target the current source revision and the next prerelease.
 
 ## Trust boundary
 
@@ -42,7 +42,9 @@ The persistent Bot adapter is registered only after a pairing file passes strict
 
 Codex and the VM companion make outbound WebSocket connections. Before allocating a Durable Object, the included relay derives and checks the bearer for that exact channel and rejects browser-originated connections. Application frames use AES-256-GCM with random nonces and authenticated data binding the protocol version, channel, and sender role. The relay routes opaque frames between one `codex` and one `bridge` socket per channel, caps frames at 128 KiB, stores no payloads or credentials, and contains no payload logging. Default Cloudflare invocation logs and traces are explicitly disabled because the channel appears in the request path. The relay can still observe live connection timing, IP metadata, the random channel, and roles; it can drop, replay, or delay traffic, but it cannot decrypt or forge valid frames without the pairing key. The included deployment master is intended for one operator's self-hosted relay, not a shared public service.
 
-Each request also carries an authenticated timestamp and UUID. The companion rejects requests older than 60 seconds before invoking the gateway, persists send UUIDs to a private bounded ledger before delivery, and caches authenticated responses in memory. The ledger uses a mode-`0700` persistent XDG state directory and mode-`0600` markers; unpairing does not remove fresh markers. A same-process duplicate receives the original receipt; a replay after restart is blocked and reported as `outcome_unknown`. One process-wide in-flight guard remains active across relay reconnects. An exclusive config-path lease prevents concurrent companions, forced re-pairing, or unpairing from racing a live process. Stale leases fail closed and require operator-verified manual removal; the connector never races to reclaim them automatically. The same UUID is also sent as the gateway `clientNonce`, but callers do not rely on undocumented host deduplication.
+Each request also carries an authenticated timestamp and UUID. The companion rejects requests older than 60 seconds before invoking the gateway, persists send UUIDs to a private bounded ledger before delivery, and caches authenticated responses in memory. The ledger uses a mode-`0700` persistent XDG state directory and mode-`0600` markers; unpairing does not remove fresh markers. A same-process duplicate receives the original receipt; a replay after restart is blocked and reported as `outcome_unknown`. One process-wide in-flight guard remains active across relay reconnects. An exclusive config-path lease prevents concurrent companions, forced re-pairing, or unpairing from racing a live process. Generic stale leases fail closed. The managed lifecycle may clear only the same private lease after two identity checks prove its recorded Linux process is gone; failed-candidate cleanup also requires the exact launch token. Active or unknown identities are never cleared. The same UUID is also sent as the gateway `clientNonce`, but callers do not rely on undocumented host deduplication.
+
+The managed lifecycle uses a detached Node child because the verified Grok Bot VM exposes no systemd, supervisord, or PM2 service manager. Install and update resolve the currently invoked package to one exact version, stage it under a private XDG data directory, validate its npm SHA-512 record, pairing identity, and local gateway before cutover, then wait for a private readiness receipt. Restart, ensure, and rollback use retained exact releases and do not resolve a mutable channel. The long-lived child receives only home and XDG paths, required Grok gateway discovery values, and its managed launch fields. It inherits no npm, provider, cloud, or unrelated application environment variables. Pairing is read before and after cutover but never copied, rewritten, or printed.
 
 The companion uses a Node-20-compatible local client for a bounded loopback-only command set: discovery, health, `listAgents`, transcript-tail and activity-status reads, and exact-ID `sendPrompt`. The contract was cross-checked against the MIT-licensed `grokbot-sdk`; the full SDK is not installed because it declares Node.js 22 while the verified VM provides Node.js 20. Each whole bridge operation pins one verified descriptor/token snapshot, including its roster check and subsequent reads or send. Every subrequest verifies that snapshot before dispatch and again after the complete bounded body passes schema validation; rotation fails closed without retry. For a send, any failure after send dispatch remains delivery-uncertain. Standalone client calls outside a bridge operation resolve a fresh snapshot per request. The client also bounds response bytes and duration, rejects redirects and non-loopback URLs, normalizes an upstream wildcard bind advertisement to `127.0.0.1` instead of connecting to the wildcard address, validates descriptor ownership and permissions, verifies on Linux that the descriptor PID owns the listening socket, validates response shapes, and sanitizes errors. The gateway token stays in VM memory and is never returned to Codex or the relay. The companion does not expose arbitrary gateway commands, raw transcript rows, files, shell, delete/reset, or credential APIs. It refreshes the roster before every read or send.
 

package/dist/bridge-companion.d.ts

@@ -2,6 +2,7 @@
 import { type LocalAgentSummary, type LocalGatewayDiscovery, type LocalGatewayHealth, type LocalSendPromptInput } from "./grok-bot-client.js";
 import { type BridgeRequest, type BridgeResponse } from "./bridge-protocol.js";
 import { type PairingConfig } from "./bridge-pairing.js";
+import { type LifecycleCommand, type LifecycleResult } from "./bridge-lifecycle.js";
 export type BridgeProbeClient = {
     discovery(): Pick<LocalGatewayDiscovery, "port" | "pid" | "hasToken">;
     health(): Promise<Pick<LocalGatewayHealth, "ok" | "isBusy">>;
@@ -47,6 +48,10 @@ type Writer = {
 };
 type CliDependencies = {
     createClient?: () => BridgeClient;
+    environment?: NodeJS.ProcessEnv;
+    lifecycle?: {
+        run(command: LifecycleCommand): Promise<LifecycleResult>;
+    };
     readPairCode?: () => Promise<string>;
     runBridge?: (config: PairingConfig, client: BridgeClient) => Promise<void>;
     configPath?: string;
@@ -56,6 +61,6 @@ type CliDependencies = {
 export declare function createBridgeProbeClient(): BridgeClient;
 export declare function probeBridge(client: BridgeProbeClient): Promise<BridgeProbeResult>;
 export declare function handleBridgeRequest(client: BridgeClient, request: BridgeRequest): Promise<BridgeResponse>;
-export declare function runBridge(config: PairingConfig, client?: BridgeClient, signal?: AbortSignal, replayRoot?: string): Promise<void>;
+export declare function runBridge(config: PairingConfig, client?: BridgeClient, signal?: AbortSignal, replayRoot?: string, onReady?: () => Promise<void>): Promise<void>;
 export declare function runBridgeCompanion(argv: string[], dependencies?: CliDependencies): Promise<number>;
 export {};