feat(install): add a grokbot host that stages a Grok Bot marketplace

.changeset/grokbot-install-host.md

@@ -0,0 +1,5 @@
+---
+'agent-bundle': patch
+---
+
+Add a `grokbot` install host. `agent-bundle install grokbot` (and `<bundle>-install install grokbot` from package-bound installer bins) stages the bundle's Cursor projection as a committed marketplace repository under `~/.grokbot/agent-bundle/marketplaces/<name>` with a store receipt, and prints the remaining Grok Bot steps: host the repository, add it as a plugin marketplace, and install the plugin from Grok Bot's Marketplace, which assigns the plugin id server-side. `agent-bundle doctor --host grokbot` reports the plugin id and installed commit from the Grok Bot computer's plugin cache (`AB7334`), and `agent-bundle uninstall grokbot` removes the staging and receipt and names the plugin id to uninstall in Grok Bot. (#864)

docs/diagnostics.md

@@ -38,7 +38,7 @@ even when no error diagnostic was reported.
 | `AB7010`–`AB7015` | npm prepack inventory, artifact freshness, package bin targets, release-version agreement, and installed-dependency hygiene (`AB7014`: a dependency no consumer-runtime evidence requires; `AB7015`: a git, remote-tarball, path, or unrewritten workspace-protocol dependency specifier). |
 | `AB7200`–`AB7202`, `AB7210`–`AB7211` | Development rebuilds and live host surfaces: rebuild admission and phase failures, development host install sync, and the dev-epoch contract gate (see below). |
 | `AB7xxx` | Project preparation and development rebuilds (`AB7100`–`AB7102`: a development rebuild's compilation, publication, and cleanup; `AB7101` is also the one-shot `build` / `build()` refusal when source changes during compilation; `AB7103`: the development package build; see below). |
-| `AB7300`–`AB7333` | Read-only install Doctor: host probes, installed inventory, bundle comparison and registration proof, runtime endpoint health and identity, durable-state inventory, static bytes-at-rest validation, foreign-install detection (`AB7321`; see below), Cursor plugin hook registration / marketplace staging (`AB7322`–`AB7324`; see below), host load refusal (`AB7325`; see below), the Cursor Agent Plugins launch proof (`AB7326`; see below), a disabled Claude install (`AB7327`; see below), lifecycle receipts and activation states (`AB7328`–`AB7330`; see below), the operator `.env` layer of an installed pack (`AB7331`; see below), the retired `AB7332` (see below), and dangling receipt-owned marketplaces (`AB7333`; see below). `AB7311` and `AB7325` are also emitted by `build` and `validate --artifact` from the Claude load check (see "Claude Code host validation"). |
+| `AB7300`–`AB7334` | Read-only install Doctor: host probes, installed inventory, bundle comparison and registration proof, runtime endpoint health and identity, durable-state inventory, static bytes-at-rest validation, foreign-install detection (`AB7321`; see below), Cursor plugin hook registration / marketplace staging (`AB7322`–`AB7324`; see below), host load refusal (`AB7325`; see below), the Cursor Agent Plugins launch proof (`AB7326`; see below), a disabled Claude install (`AB7327`; see below), lifecycle receipts and activation states (`AB7328`–`AB7330`; see below), the operator `.env` layer of an installed pack (`AB7331`; see below), the retired `AB7332` (see below), dangling receipt-owned marketplaces (`AB7333`; see below), and the opt-in Grok Bot report (`AB7334`; see below). `AB7311` and `AB7325` are also emitted by `build` and `validate --artifact` from the Claude load check (see "Claude Code host validation"). |
 | `AB8200`–`AB8209` | Workbench development runtime routes (`/api/runtime/**`): `AB8200` development runtime provider configuration, load, or lifecycle failure, `AB8201` runtime/session/run not available, `AB8202` invalid route path, `AB8203` invalid request shape, `AB8204` stale runtime generation (409), `AB8205` runtime request could not be completed, `AB8206` Workbench runtime client failure, `AB8207` Agent Document decoding needs the optional `@agent-bundle/runtime` peer (503), `AB8208` stored Flight could not be decoded as an Agent Document (409), `AB8209` decoded Agent Document over the 16 MiB budget (413) or an invalid document response. |
 | `AB8210`–`AB8214` | Workbench semantic lifecycle replay routes (`/api/lifecycles`, `/api/lifecycles/replays`): `AB8210` invalid path, `AB8211` malformed replay request or native envelope (400, carries the shared validator message), `AB8212` replay unavailable or could not be completed, `AB8213` stale manifest binding (409; the page repairs it with refresh → explicit re-run), `AB8214` replay over the 16 MiB budget (413). |
 | `AB8215`–`AB8218` | Workbench read-only host discovery route (`/api/discovery`): `AB8215` invalid path, `AB8216` query string or non-`GET` method (400/405), `AB8217` report over the 16 MiB response limit (413), `AB8218` discovery not available (503). |
@@ -1261,6 +1261,22 @@ state, never purged, and is listed by `uninstall` as retained.
 | --- | --- | --- |
 | `AB7333` | error | A Claude or Codex marketplace recorded as Agent Bundle-owned by an install receipt points at a source directory that no longer exists. Run `agent-bundle uninstall <host> --from <bundle-dir> --force`, or remove the named marketplace with the host CLI. |
 
+## Read-only Doctor Grok Bot report (`AB7334`)
+
+`agent-bundle doctor --host grokbot` (never part of the default host set) reads
+the receipts `install grokbot` wrote under `~/.grokbot/agent-bundle` (or
+`$GROK_BOT_HOME/agent-bundle`) and, on the Grok Bot computer, every completed
+copy of the plugin in `<agent-data>/plugins/cache/<marketplace>/<plugin>/<commit>/`
+together with the server-assigned plugin id from `<agent-data>/plugin-skills/cache.json`
+(`GROK_BOT_AGENT_DATA_DIR`, then `/home/box/agent-data`, `~/.grokbot/agent-data`,
+and the macOS application-support root). It never touches the account-level
+install. A plugin that contributes no skill has no skill-index row, so its id reads
+as not assigned even when the cache copy exists.
+
+| Code | Severity | Trigger |
+| --- | --- | --- |
+| `AB7334` | info / warning | With `--from`: the bundle's Grok Bot state, not installed (and whether a staged marketplace awaits hosting), or installed with each copy's plugin id, manifest version, installed commit, and marketplace; warning when every installed copy has a different version than the bundle. Host the staged marketplace and install the plugin from Grok Bot's Marketplace; for a version warning push the rebuilt marketplace and update the plugin in Grok Bot. |
+
 ## Read-only runtime identity introspection (`AB7317`–`AB7318`)
 
 | Code | Severity | Trigger |
@@ -1832,11 +1848,11 @@ the uninstall refusals `AB7007`–`AB7009`, have their own sections above.
 
 | Code | Severity | Meaning | Recovery |
 | --- | --- | --- | --- |
-| `AB7000` | error | Install/uninstall: `Unsupported install host <host>.` / `Unsupported uninstall host <host>.`, the exhaustive host switch received a host that is not `amp`, `claude`, `codex`, or `cursor`. Project preparation: `Unable to load project source.`, evaluating the configuration module or discovering source threw before validation. | Install: pass `--host amp`, `claude`, `codex`, or `cursor`. Preparation: fix the Agent Bundle configuration and source files, then inspect again. |
+| `AB7000` | error | Install/uninstall: `Unsupported install host <host>.` / `Unsupported uninstall host <host>.`, the exhaustive host switch received a host that is not `amp`, `claude`, `codex`, `cursor`, or `grokbot`. Project preparation: `Unable to load project source.`, evaluating the configuration module or discovering source threw before validation. | Install: pass `amp`, `claude`, `codex`, `cursor`, or `grokbot`. Preparation: fix the Agent Bundle configuration and source files, then inspect again. |
 | `AB7001` | error | Install/uninstall/doctor: the bundle identity or authoritative file inventory is unreadable from `agent-bundle.manifest.json`, no manifest directly under the `--from` directory (the composite root is every selected host's bundle root, so `<from>/<host>` is never probed and host documents are never read for identity); a manifest that is not the canonical `manifestVersion: 5` document (the message carries the parser's reason); a manifest with no projection whose `builtInHost` is the requested host (identity is the shipped adapter, never the selected name), whose projection has neither its required `documents.plugin` nor Amp `documents.entry`, or whose `documents.entry` / `documents.plugin` / `documents.marketplace` pointer names a file the root does not contain; a `files[]` row whose path is missing or whose size, digest, bytes, or executable state is invalid after installation (a declared package bin must remain executable; a file the manifest does not declare executable must remain non-executable; another manifest executable may have lost its bit while being packed from a filesystem without executable modes); a Cursor or Amp `application.name` that is not a safe local plugin name; a Claude or Codex projection with no `marketplace.name`. `install` restores manifest modes before copying an npm-installed artifact into a host, while Doctor only compares. Project preparation: `Unable to validate project source.`, `Unable to normalize project source.`, `Unable to validate normalized project.`, or `Unable to create project context.`, the source validator, normalizer, adapter planner, or project-context factory threw; `inspectProject` adds `Unable to prepare inspection plans.` and, for `inspect --bundler`, `Unable to compose the bundler inspection: <reason>`, loading entries, generating the declaration tsconfig, or lowering and asserting the build's own Rslib/Rsbuild configuration failed. The reason carries the underlying source, project-tsconfig, toolchain, or invariant error, including a `tools` value the build would refuse. | Install: point `--from` at the unchanged composite root `agent-bundle build` wrote, rebuilt with the host among `targets`; if a listed file is missing or changed, rebuild or restore that file from the matching artifact. Preparation: fix normalized project configuration and source references, then inspect again. Bundler inspection: fix the source, project tsconfig, toolchain, or refused `tools` value named by the reason. |
-| `AB7002` | error | Install/uninstall: `<host> is not installed or is not available on PATH.`, `Cursor is not installed in "<root>".` / `Cursor home "<root>" is not a directory.`, or `git` is missing for `--mode marketplace`. Project preparation: `Unable to prepare project paths.`, the project root or a configured output root could not be resolved inside the project. | Install: install the host CLI the message names; for the `git` refusal, install git or use `--mode local`. Preparation: ensure the project root and configured output roots are readable and remain inside the project root, then inspect again. |
-| `AB7003` | error | Install/uninstall scope and mode refusals: `--mode` on a host other than `cursor`; `--scope` other than `user` for Codex or Cursor; Amp `--scope local` instead of `project` or `user`; `--mode marketplace` without `.cursor-plugin/plugin.json` or with bundle-internal Git metadata. Project preparation: `Unable to snapshot project source.`, the source snapshot could not be taken, including when a discovered identity is not a relocatable POSIX path (a POSIX filename containing `\`, or another segment the manifest cannot carry). | Install: use a documented host scope, drop `--mode` for non-Cursor hosts, or, as the message says, stage a Cursor Plugin bundle without `.git`, or use `--mode local`. Preparation: ensure project source files and ignore rules are readable, remain inside the project root, and use relocatable POSIX path segments, then inspect again. |
-| `AB7004` | error | Install/uninstall command and safety failures: `<host> plugin <operation> failed: <detail>` (a host CLI verb exited nonzero); `<host> plugin list --json` was unusable when `--replace` or an uninstall needed it; an installed copy could not be compared and `--replace` was not given; a Codex replacement whose plugin list row is `enabled: false` or omits `enabled` (the native plugin CLI has no qualified settings-preserving update API, and native `plugin add` would set enabled to true); a rollback after a failed install also failed (the message lists the host verbs to run by hand); a Cursor marketplace `git` step failed or the committed tree differs from the staged bytes; or any non-diagnostic error thrown by a Cursor installer. `inspectProject`: `Requested inspection target "<name>" is not selected for this project.` | Install: read the host's detail in the message, then rerun (with `--replace` where the message says so). For a Codex disabled/unknown-enablement refusal, enable the plugin in Codex first. Inspection: choose a target selected by the project configuration, then inspect again. |
+| `AB7002` | error | Install/uninstall: `<host> is not installed or is not available on PATH.`, `Cursor is not installed in "<root>".` / `Cursor home "<root>" is not a directory.`, or `git` is missing for `--mode marketplace` or `install grokbot`. Project preparation: `Unable to prepare project paths.`, the project root or a configured output root could not be resolved inside the project. | Install: install the host CLI the message names; for the `git` refusal, install git (Cursor can also use `--mode local`; `grokbot` has no local mode). Preparation: ensure the project root and configured output roots are readable and remain inside the project root, then inspect again. |
+| `AB7003` | error | Install/uninstall scope and mode refusals: `--mode` on a host other than `cursor` (including `grokbot`, which always stages a marketplace); `--scope` other than `user` for Codex, Cursor, or Grok Bot; Amp `--scope local` instead of `project` or `user`; `--mode marketplace` (or `install grokbot`) without `.cursor-plugin/plugin.json` or with bundle-internal Git metadata. Project preparation: `Unable to snapshot project source.`, the source snapshot could not be taken, including when a discovered identity is not a relocatable POSIX path (a POSIX filename containing `\`, or another segment the manifest cannot carry). | Install: use a documented host scope, drop `--mode` for non-Cursor hosts, or, as the message says, stage a Cursor Plugin bundle without `.git`, or use `--mode local` (for `grokbot`, list `cursor` in the bundle targets instead). Preparation: ensure project source files and ignore rules are readable, remain inside the project root, and use relocatable POSIX path segments, then inspect again. |
+| `AB7004` | error | Install/uninstall command and safety failures: `<host> plugin <operation> failed: <detail>` (a host CLI verb exited nonzero); `<host> plugin list --json` was unusable when `--replace` or an uninstall needed it; an installed copy could not be compared and `--replace` was not given; a Codex replacement whose plugin list row is `enabled: false` or omits `enabled` (the native plugin CLI has no qualified settings-preserving update API, and native `plugin add` would set enabled to true); a rollback after a failed install also failed (the message lists the host verbs to run by hand); a Cursor or Grok Bot marketplace `git` step failed or the committed tree differs from the staged bytes; or any non-diagnostic error thrown by a Cursor installer. `inspectProject`: `Requested inspection target "<name>" is not selected for this project.` | Install: read the host's detail in the message, then rerun (with `--replace` where the message says so). For a Codex disabled/unknown-enablement refusal, enable the plugin in Codex first. Inspection: choose a target selected by the project configuration, then inspect again. |
 
 ## Development server (`AB80xx`)
 

packages/agent-bundle/README.md

@@ -221,6 +221,16 @@ Cursor manage the plugin as a marketplace install; `agent-bundle doctor --host
 cursor` reports hook registration (`AB7322`), duplicate user-level delivery
 (`AB7323`), and marketplace import state (`AB7324`).
 
+`agent-bundle install grokbot` (or `<bin> install grokbot` from a package-bound
+installer) stages the same Cursor projection as a committed marketplace
+repository at `~/.grokbot/agent-bundle/marketplaces/<name>` and prints the
+steps Grok Bot needs: host the repository on GitHub, add it as a plugin
+marketplace, and install the plugin from Grok Bot's Marketplace. Grok Bot
+assigns the plugin id server-side, so nothing is registered locally;
+`agent-bundle doctor --host grokbot` reports that id and the installed commit
+from the Grok Bot computer's plugin cache (`AB7334`), and `uninstall grokbot`
+removes the staging and names the id to uninstall in Grok Bot.
+
 For a root whose only Cursor-loadable format is the `portable` projection,
 `install.mjs` copies the Agent Plugins package to the same
 `~/.cursor/plugins/local/<name>` location and, because Cursor 3.18.25

packages/agent-bundle/src/dev/playground/host-discovery-service.ts

@@ -117,8 +117,11 @@ const discoveryMcpServer = (value: ModernMcpServerEntry): DiscoveryMcpServer =>
   transport: value.server.kind,
 });
 
+/** Workbench discovery covers the hosts with a full Doctor report; the opt-in `grokbot` report is not one of them. */
+type DiscoverableHostReport = DoctorHostReport & { readonly host: Exclude<DoctorHostReport['host'], 'grokbot'> };
+
 const enumerateMcpServers = async (
-  value: DoctorHostReport,
+  value: DiscoverableHostReport,
   registry: TargetRegistry,
   run: PlatformRun,
 ): Promise<readonly DiscoveryMcpServer[] | undefined> => {
@@ -142,7 +145,7 @@ const enumerateMcpServers = async (
 };
 
 const hostReport = async (
-  value: DoctorHostReport,
+  value: DiscoverableHostReport,
   registry: TargetRegistry,
   run: PlatformRun,
 ): Promise<DiscoveryHostReport> => Object.freeze({
@@ -208,7 +211,9 @@ export class HostDiscoveryService implements HostDiscoveryRouteService {
       ...(bundleSource ? { from: bundleSource } : {}),
     });
     const hosts: readonly DiscoveryHostReport[] = Object.freeze(
-      await Promise.all(report.hosts.map((value) => hostReport(value, this.#registry, this.#run))),
+      await Promise.all(report.hosts
+        .filter((value): value is DiscoverableHostReport => value.host !== 'grokbot')
+        .map((value) => hostReport(value, this.#registry, this.#run))),
     );
     const endpoints: DiscoveryEndpointReport = endpointReport(report.endpoints);
     const diagnostics: readonly DiscoveryDiagnostic[] = Object.freeze(