feat(grok): add Grok Build (xAI) as a seventh CLI run mode

SessionMode gains 'grok', a first-class backend alongside Claude Code,
shell, OpenCode, Codex, Gemini, Antigravity and Pi: its own PTY, tmux
session, charcoal tab identity ('gk' badge), welcome button, run-mode
entry, cron agentType, Docker and remote-SSH command defaults, and
clone-repo Brain option. Flag surface verified live against grok 1.0.5.

Grok mixes two existing shapes and the wiring follows from that:

- Codex-shaped on permissions: the bypass switch is GrokConfig.alwaysApprove
  (--always-approve, grok's bypassPermissions mode; config-level deny rules
  still apply on top). The Run button sends it true, like runAntigravity(),
  and clampExternalCliBypassForOwner() puts grok in the only-if-sent branch:
  a bare grok spawn is grok's own ask-mode default, which is already safe,
  so only a sent config needs the flag forced off. Cron needs nothing for
  the same reason.
- OpenCode-shaped on rendering: grok is a fullscreen alternate-screen TUI
  with mouse support, so it stays OUT of isAltScreenStripMode() and lands
  on the narrow tmux-attach strip and the 'buffer' local-echo fallthrough
  (unmeasured against an authenticated composer; documented fallback is the
  'off' branch).
- Pi-shaped on resolution: 'grok' has npm squatters (@vibe-kit/grok-cli
  also installs a grok bin), so grok-cli-resolver.ts version-probes every
  candidate (grok --version, killSignal SIGKILL, VITEST-gated) and
  GET /api/grok/status surfaces path AND version; GROK_VERSION_REGEX is
  shared with the dependency registry so doctor and run mode cannot drift.

Env allowlist gains GROK_* plus the XAI_* vendor namespace (XAI_API_KEY is
grok's documented headless auth var), the same narrow-vendor reasoning as
GOOGLE_* for gemini. Resume is id-regexed on purpose: grok's own --resume
also matches session titles, which are arbitrary user strings that must
never reach the bash -c spawn line.

Docker: grok is not on npm, so the agent image installs it in its own step
(xAI's installer has no --dir override; the binary is copied to
/usr/local/bin and root's ~/.grok dropped in the same layer), and
credentials are seeded per-file (auth.json, config.toml, pager.toml; the
dir also holds sessions/, memory/ and the ~160MB binary). Remote SSH routes
through the login-shell wrapper like the other agent CLIs.

Verified end to end on an isolated CODEMAN_INSTANCE with grok 1.0.5
installed: /api/grok/status resolves and reports the probed version,
quick-start spawns a pane whose command line ends in 'grok
--always-approve', the real TUI renders (OAuth device screen on an
unauthenticated box), and grokConfig round-trips through state.json.
Docs: docs/grok-integration.md (user guide) + docs/grok-integration-plan.md
(decisions, verification record, follow-ups).

Tests: test/grok-mode.test.ts, test/grok-cli-resolver.test.ts, plus
extended clamp/system-routes/render-index-html/run-mode-ui/mobile-overview/
local-echo-gating coverage. npm test (the CI gate) green: 5910 tests.

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

src/utils/cli-executable-resolver.ts

@@ -1,8 +1,8 @@
 /**
  * @fileoverview Shared CLI executable resolution for the per-CLI resolvers.
  *
- * One lookup chain behind all six *-cli-resolver modules (claude, opencode,
- * codex, gemini, antigravity, pi): the server process PATH first, then the
+ * One lookup chain behind all seven *-cli-resolver modules (claude, opencode,
+ * codex, gemini, antigravity, pi, grok): the server process PATH first, then the
  * CLI's common install directories in order, then — last, because it is the
  * only step that spawns anything — an interactive login shell, which is what
  * finds nvm/Homebrew/user-npm installs when Codeman runs as a systemd/launchd

src/utils/grok-cli-resolver.ts

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Resolve the Grok Build CLI (`grok`, xAI) binary across common install paths.
+ *
+ * Mirrors pi-cli-resolver.ts, version probe included: `grok` is another short
+ * name with known squatters (the unrelated `@vibe-kit/grok-cli` npm package also
+ * installs a `grok` bin), so a `which grok` hit is not by itself evidence that
+ * xAI's coding agent is installed. Every candidate is sanity-probed with
+ * `grok --version` and required to print a version-shaped string (the real CLI
+ * prints `grok 1.0.5 (5115b46bc9)`); a binary that fails the probe is treated
+ * as absent and the rejected path is logged. The probe cannot tell two
+ * version-printing `grok`s apart, which is why `GET /api/grok/status` surfaces
+ * path AND version: a misresolution is diagnosable rather than presenting as
+ * "the mode just doesn't work".
+ *
+ * The official installer (`curl -fsSL https://x.ai/cli/install.sh | bash`)
+ * places the binary in `~/.grok/bin` and symlinks it into `~/.local/bin`, so
+ * those two head the search list.
+ *
+ * @module utils/grok-cli-resolver
+ */
+
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { EXEC_TIMEOUT_MS } from '../config/exec-timeout.js';
+import {
+  createCliExecutableResolver,
+  formatCliNotFoundMessage,
+  type CliResolverHost,
+} from './cli-executable-resolver.js';
+
+/** Common directories where the Grok CLI binary may be installed */
+const GROK_SEARCH_DIRS = [
+  join(homedir(), '.grok', 'bin'),
+  join(homedir(), '.local', 'bin'),
+  '/usr/local/bin',
+  join(homedir(), 'bin'),
+];
+
+/**
+ * A real `grok --version` prints `grok 1.0.5 (5115b46bc9)` (measured, 1.0.5).
+ *
+ * Exported and SHARED with the `grok` entry in `config/dependency-registry.ts`,
+ * so `codeman doctor` and the run mode cannot disagree about what counts as an
+ * installed grok (the same single-source rule as PI_VERSION_REGEX). Shape is
+ * dictated by the doctor's `extractVersion()` (first capture group, whole-output
+ * scan): hence a capturing group and a leading boundary instead of `^`. No `g`
+ * flag, so there is no shared `lastIndex` to reset.
+ */
+export const GROK_VERSION_REGEX = /(?:^|\s)(\d+\.\d+\.\d+)/;
+
+const GROK_NOT_FOUND = 'Grok CLI not found. Install with: curl -fsSL https://x.ai/cli/install.sh | bash';
+
+/**
+ * Run `grok --version` on a candidate path and return the version token when it
+ * looks like the coding agent. Returns null for anything else: a missing
+ * binary, a non-zero exit, a hang (timeout), or output with no version-shaped
+ * token (which is how an unrelated `grok` on PATH gets rejected).
+ *
+ * Never runs under vitest: the suites must stay hermetic and must not depend on
+ * whether the dev box happens to have grok installed, and since `grok` is a
+ * name with known squatters, this probe would EXECUTE whatever binary of that
+ * name the machine carries. The shared resolver host is already inert under
+ * vitest, so this gate is defense in depth for any opted-in host that still
+ * carries the default probe; tests drive resolution via
+ * `createGrokResolverForTest`, whose injected probe bypasses it. Pinned by
+ * test/grok-cli-resolver.test.ts.
+ */
+function probeGrokVersion(binPath: string): string | null {
+  if (process.env.VITEST) return null;
+  try {
+    const out = execFileSync(binPath, ['--version'], {
+      encoding: 'utf-8',
+      timeout: EXEC_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      // A stuck or hostile `grok` that ignores SIGTERM would survive the timeout
+      // and block the server (execFileSync keeps waiting after the signal).
+      killSignal: 'SIGKILL',
+    }).trim();
+    const candidate = GROK_VERSION_REGEX.exec(out)?.[1];
+    if (candidate) return candidate;
+    console.warn(`[GrokResolver] Ignoring ${binPath}: "grok --version" printed ${JSON.stringify(out.slice(0, 80))}`);
+  } catch (err) {
+    console.warn(`[GrokResolver] Ignoring ${binPath}: "grok --version" failed (${(err as Error).message})`);
+  }
+  return null;
+}
+
+type GrokVersionProbe = (binPath: string) => string | null;
+
+function createGrokResolver(
+  host?: CliResolverHost,
+  versionProbe: GrokVersionProbe = probeGrokVersion,
+  now?: () => number
+) {
+  return createCliExecutableResolver<string>(
+    {
+      binary: 'grok',
+      searchDirs: GROK_SEARCH_DIRS,
+      validateCandidate: (binPath) => {
+        const version = versionProbe(binPath);
+        return version ? { accepted: true, metadata: version } : { accepted: false };
+      },
+      now,
+    },
+    host
+  );
+}
+
+/**
+ * Creates an isolated Grok wrapper around an injected host, version probe and
+ * clock. Omitting `versionProbe` keeps the ambient (VITEST-gated) probe, which
+ * is exactly what the hermeticity test exercises.
+ */
+export function createGrokResolverForTest(host: CliResolverHost, versionProbe?: GrokVersionProbe, now?: () => number) {
+  return createGrokResolver(host, versionProbe ?? probeGrokVersion, now);
+}
+
+const grokResolver = createGrokResolver();
+
+/**
+ * Finds the directory containing a verified `grok` binary.
+ * Checks the server PATH first, then the common install locations
+ * (`~/.grok/bin` leading, the official installer's target). Every candidate
+ * must pass the `grok --version` sanity probe before it is accepted.
+ *
+ * @returns Directory path, or null if not found
+ */
+export function resolveGrokDir(): string | null {
+  return grokResolver.resolve()?.directory ?? null;
+}
+
+/**
+ * Check if the Grok CLI is available on the system.
+ */
+export function isGrokAvailable(): boolean {
+  return resolveGrokDir() !== null;
+}
+
+export function getGrokNotFoundMessage(): string {
+  return formatCliNotFoundMessage(GROK_NOT_FOUND, grokResolver.diagnostics());
+}
+
+/**
+ * Version reported by the resolved `grok` binary, or null when grok is
+ * unavailable. Surfaced through `GET /api/grok/status` so a misresolution is
+ * diagnosable from the UI.
+ */
+export function getGrokCliVersion(): string | null {
+  return grokResolver.resolve()?.metadata ?? null;
+}

src/utils/index.ts

@@ -45,5 +45,6 @@ export {
   getAntigravityNotFoundMessage,
 } from './antigravity-cli-resolver.js';
 export { resolvePiDir, isPiAvailable, getPiCliVersion, getPiNotFoundMessage } from './pi-cli-resolver.js';
+export { resolveGrokDir, isGrokAvailable, getGrokCliVersion, getGrokNotFoundMessage } from './grok-cli-resolver.js';
 export { compileFileQuery, matchFileQuery } from './file-query.js';
 export type { FileQueryMatcher } from './file-query.js';