@brimveyn/aimux 1.19.3 → 1.19.4

package/README.md

@@ -13,7 +13,7 @@ snippets, themes, and fully configurable keymaps.
 ## Features
 
 - multi-workspace workflow with a dedicated workspace picker
-- tabs for `claude`, `codex`, `opencode`, and `terminal`
+- tabs for `claude`, `codex`, `opencode`, `grok`, and `terminal`
 - split panes with pane focus and resize shortcuts
 - persistent workspaces with saved layout and tab state
 - profile-isolated config, catalogs, daemon sockets, and runtime state

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.19.3",
+  "version": "1.19.4",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",
@@ -64,7 +64,7 @@
     "bump:terminal_manager": "bun run scripts/bump-protocol.ts terminal-manager"
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.8.1",
+    "@brimveyn/aimux-config": "0.8.2",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
     "@resvg/resvg-wasm": "^2.6.2",

package/src/auto-commit/headless-commands.ts

@@ -3,9 +3,14 @@ export interface HeadlessInvocation {
   args: string[]
 }
 
-export type SupportedProvider = 'claude' | 'codex' | 'opencode'
+export type SupportedProvider = 'claude' | 'codex' | 'opencode' | 'grok'
 
-const SUPPORTED: ReadonlySet<string> = new Set<SupportedProvider>(['claude', 'codex', 'opencode'])
+const SUPPORTED: ReadonlySet<string> = new Set<SupportedProvider>([
+  'claude',
+  'codex',
+  'opencode',
+  'grok',
+])
 
 export function isSupportedProvider(id: string): id is SupportedProvider {
   return SUPPORTED.has(id)
@@ -32,6 +37,13 @@ export function buildHeadlessInvocation(
     case 'opencode': {
       return { args: ['run', prompt], executable: 'opencode' }
     }
+    case 'grok': {
+      // Headless: grok -p "<prompt>" [-m <model>]. Model appended after prompt value to
+      // match documented example shape `grok -p "..." -m my-model`. No output-format flag.
+      const args: string[] = ['-p', prompt]
+      if (model != null && model !== '') args.push('-m', model)
+      return { args, executable: 'grok' }
+    }
     default:
       return null
   }

package/src/cli/commands/tab/await-turn.ts

@@ -0,0 +1,159 @@
+/**
+ * Shared turn-lifecycle waiter behind `tab run` (submit + await) and `tab await`
+ * (await only). It subscribes to the daemon's v13 events
+ * (`tabStatus`/`tabTurnComplete`/`tabQuestion`/`tabExit`/`tabError`) and settles
+ * on the first terminal signal or the overall timeout. Settlement rides the
+ * daemon's edge-triggered events — the daemon applies the idle settle window
+ * before emitting `tabTurnComplete`, and `tabQuestion` fires only on a real
+ * transition into `waiting-input` with daemon-captured text — so this never
+ * scrapes the screen and can't misread a working footer as a prompt.
+ */
+import type { QuestionKind } from '../../../state/types'
+import type { DaemonClient } from '../../client/daemon-client'
+
+import { EXIT_OK, EXIT_QUESTION, EXIT_RUNTIME, EXIT_TIMEOUT } from '../../output'
+
+/** Overall cap on a single turn — 15 min, long enough for a heavy build task. */
+export const DEFAULT_TIMEOUT_MS = 900_000
+
+/**
+ * The four terminal shapes of a turn. A discriminated union so the JSON emitted
+ * and the exit code returned derive from one value, and the outcome→exit map is
+ * unit-testable without a live daemon. `durationMs` is measured from the moment
+ * the turn is armed (post-submit for `tab run`, from attach for `tab await`).
+ */
+export type TurnOutcome =
+  | { durationMs: number; outcome: 'completed' }
+  | { durationMs: number; error: string; outcome: 'error' }
+  | {
+      durationMs: number
+      kind: QuestionKind
+      options?: string[]
+      outcome: 'question'
+      question: string
+    }
+  | { durationMs: number; outcome: 'timeout' }
+
+/**
+ * Map an outcome to its process exit code. Pure and total over the union so a
+ * driver's `case $?` stays exhaustive: 0 completed, 10 question/permission
+ * (worker blocked wanting input), 3 the tab errored/exited, 124 overall cap.
+ */
+export function turnOutcomeExitCode(outcome: TurnOutcome): number {
+  switch (outcome.outcome) {
+    case 'completed':
+      return EXIT_OK
+    case 'question':
+      return EXIT_QUESTION
+    case 'error':
+      return EXIT_RUNTIME
+    case 'timeout':
+      return EXIT_TIMEOUT
+  }
+}
+
+export interface AwaitTurnOptions {
+  daemon: DaemonClient
+  tabId: string
+  timeoutMs: number
+  /**
+   * Seed the uptake guard. `tab run` passes `false` — only a post-submit
+   * `working` transition validates completion, so a lingering pre-submit idle
+   * can't be misread as "done". `tab await` passes `true` when the attach replay
+   * already shows the tab `working`: no future `working` transition will fire for
+   * a turn already in flight, so an unseeded guard would hang to timeout.
+   */
+  assumeWorking: boolean
+  /**
+   * Runs once all subscriptions are armed; the duration clock resets when it
+   * resolves. `tab run` submits the prompt here. A rejection settles as an
+   * `error` outcome (the tab likely died mid-write). `tab await` omits it.
+   */
+  onArmed?: () => Promise<void>
+}
+
+/**
+ * Subscribe to the turn-lifecycle events and resolve with the first terminal
+ * outcome. Callers own emitting the JSON and returning `turnOutcomeExitCode`.
+ */
+// `async` only to satisfy promise-function-async; the body has no `await`, so
+// the Promise executor below still runs synchronously and subscriptions are
+// armed before this returns (callers rely on emitting right after the call).
+export async function awaitTurn(opts: AwaitTurnOptions): Promise<TurnOutcome> {
+  const { assumeWorking, daemon, onArmed, tabId, timeoutMs } = opts
+  return new Promise<TurnOutcome>((resolve) => {
+    // Subscribe BEFORE arming: these events fire only on transitions, so a late
+    // subscription would race the worker starting its turn.
+    let start = Date.now()
+    let sawWorking = assumeWorking
+
+    const settle = (outcome: TurnOutcome): void => {
+      cleanup()
+      resolve(outcome)
+    }
+    const durationMs = (): number => Date.now() - start
+
+    const offStatus = daemon.on('tabStatus', (p) => {
+      if (p.tabId !== tabId) return
+      if (p.status === 'working') sawWorking = true
+    })
+    const offTurn = daemon.on('tabTurnComplete', (p) => {
+      if (p.tabId !== tabId) return
+      // Ignore end-of-turn until the worker actually started working, so a
+      // lingering pre-arm idle can't be mis-read as completion.
+      if (!sawWorking) return
+      settle({ durationMs: durationMs(), outcome: 'completed' })
+    })
+    const offQuestion = daemon.on('tabQuestion', (p) => {
+      if (p.tabId !== tabId) return
+      // A question is honoured immediately — it can legitimately arrive before
+      // `working` (the worker asks before doing anything).
+      settle({
+        durationMs: durationMs(),
+        kind: p.kind,
+        options: p.options,
+        outcome: 'question',
+        question: p.prompt,
+      })
+    })
+    const offExit = daemon.on('tabExit', (p) => {
+      if (p.tabId !== tabId) return
+      settle({ durationMs: durationMs(), error: `exit ${p.exitCode}`, outcome: 'error' })
+    })
+    const offError = daemon.on('tabError', (p) => {
+      if (p.tabId !== tabId) return
+      settle({ durationMs: durationMs(), error: p.message, outcome: 'error' })
+    })
+
+    const timer = setTimeout(() => {
+      settle({ durationMs: durationMs(), outcome: 'timeout' })
+    }, timeoutMs)
+
+    const cleanup = (): void => {
+      offStatus()
+      offTurn()
+      offQuestion()
+      offExit()
+      offError()
+      clearTimeout(timer)
+    }
+
+    // Arm after subscribing, then reset the clock so `durationMs` measures the
+    // worker's turn rather than our attach/write overhead. On failure the tab
+    // likely died — surface an error outcome rather than sitting to the timeout.
+    if (onArmed !== undefined) {
+      void (async (): Promise<void> => {
+        try {
+          await onArmed()
+          start = Date.now()
+        } catch (error) {
+          settle({
+            durationMs: durationMs(),
+            error: error instanceof Error ? error.message : String(error),
+            outcome: 'error',
+          })
+        }
+      })()
+    }
+  })
+}

package/src/cli/commands/tab/await.ts

@@ -0,0 +1,97 @@
+/**
+ * `aimux tab await <tabId>` — block until a tab's in-flight turn ends or the
+ * worker asks, without submitting anything. It's the standalone half of
+ * `tab run` for turns you started by hand (a `tab send --enter`, or a worker you
+ * nudged), sharing `awaitTurn` so the outcome JSON and exit codes are identical.
+ *
+ * The turn-lifecycle events fire only on transitions, so `awaitTurn` is seeded
+ * from the attach replay: a tab already `working` won't emit another `working`
+ * transition (assume it), an already-`waiting-input` tab's `tabQuestion` already
+ * fired (short-circuit with a best-effort snapshot tail), and an `idle` tab is
+ * awaited for a *fresh* working→idle cycle so a stale, already-finished turn is
+ * never re-reported as "completed".
+ */
+import type { CliCommand } from '../../registry'
+
+import {
+  IPC_CAPABILITY_QUESTION_EVENTS,
+  IPC_CAPABILITY_THIN_ATTACH,
+  IPC_CAPABILITY_TURN_LIFECYCLE,
+} from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { writeJson } from '../../output'
+import { snapshotTailLines } from '../../snapshot-render'
+import { awaitTurn, DEFAULT_TIMEOUT_MS, type TurnOutcome, turnOutcomeExitCode } from './await-turn'
+
+/** Lines of rendered tail to attach as the question text on a replay short-circuit. */
+const QUESTION_TAIL_LINES = 25
+
+export const tabAwait: CliCommand = {
+  args: [{ name: 'tabId', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    {
+      description: 'overall turn cap in milliseconds (default 900000 = 15 min)',
+      kind: 'number',
+      name: 'timeout',
+    },
+  ],
+  group: 'tab',
+  run: async (ctx) => {
+    const tabId = ctx.args.positionals[0]
+    if (typeof tabId !== 'string' || tabId.length === 0) {
+      throw new Error('tabId is required')
+    }
+    const timeoutMs =
+      typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_TIMEOUT_MS
+
+    const workspace = ctx.getWorkspace()
+    const daemon = await ctx.getDaemon()
+    if (
+      !daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH) ||
+      !daemon.hasCapability(IPC_CAPABILITY_TURN_LIFECYCLE) ||
+      !daemon.hasCapability(IPC_CAPABILITY_QUESTION_EVENTS)
+    ) {
+      throw new Error(
+        'daemon predates tab await (turnLifecycle/questionEvents) — restart aimux to pick up the new daemon'
+      )
+    }
+
+    const attach = await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+    const tab = attach.tabs.find((t) => t.id === tabId)
+    if (!tab) {
+      // Exit 3 (runtime) via runCli — NOT 4, which is reserved for
+      // daemon-unreachable. A driver reads "tab not found" as the re-spawn signal.
+      throw new Error(`tab not found: ${tabId}`)
+    }
+
+    if (tab.activity === 'waiting-input') {
+      // The tabQuestion event fired before we attached and won't re-fire.
+      // Reconstruct a best-effort prompt from the rendered tail (the real
+      // kind/options aren't recoverable from a replay).
+      const question =
+        tab.viewport && tab.viewport.lines.length > 0
+          ? snapshotTailLines(tab.viewport, QUESTION_TAIL_LINES, { trim: true }).join('\n')
+          : ''
+      const outcome: TurnOutcome = {
+        durationMs: 0,
+        kind: 'question',
+        outcome: 'question',
+        question,
+      }
+      writeJson(outcome)
+      return turnOutcomeExitCode(outcome)
+    }
+
+    const outcome = await awaitTurn({
+      assumeWorking: tab.activity === 'working',
+      daemon,
+      tabId,
+      timeoutMs,
+    })
+    writeJson(outcome)
+    return turnOutcomeExitCode(outcome)
+  },
+  summary: "Block until a tab's in-flight turn completes or the worker asks",
+  verb: 'await',
+}

package/src/cli/commands/tab/create.ts

@@ -2,28 +2,60 @@ import { resolve as resolvePath } from 'node:path'
 
 import type { CliCommand } from '../../registry'
 
+import { loadConfig } from '../../../config'
 import {
   IPC_CAPABILITY_CREATE_TAB_SIZE_FALLBACK,
   IPC_CAPABILITY_THIN_ATTACH,
 } from '../../../ipc/protocol'
 import { createPrefixedId } from '../../../platform/id'
 import {
+  type AssistantOption,
   buildAssistantModelArgs,
   getAllAssistantOptions,
   parseCommand,
 } from '../../../pty/command-registry'
 import { SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, writeJson } from '../../output'
+import { createWorkspaceWorktree } from '../worktree/create-core'
 
 const FALLBACK_COLS = 200
 const FALLBACK_ROWS = 60
 
+/**
+ * Resolve the cwd a spawned tab should run in. Precedence: explicit `--cwd`
+ * (resolved to absolute) > the resolved worktree's path > undefined (the
+ * daemon's default). Worktree record paths are already absolute.
+ */
+export function resolveTabCwd(
+  cwdFlag: string | undefined,
+  worktreeRecord: { path: string } | undefined
+): string | undefined {
+  if (cwdFlag !== undefined) return resolvePath(cwdFlag)
+  return worktreeRecord?.path
+}
+
+/**
+ * Resolve the base command a tab launches. Mirrors the UI's precedence
+ * (`src/app-runtime/side-effects.ts`): an explicit `--command` override wins,
+ * else the workspace's persisted `customCommands[assistantId]` (so CLI workers
+ * inherit e.g. `claude --dangerously-skip-permissions`), else the builtin
+ * default. `getAllAssistantOptions` deliberately does NOT apply builtin
+ * overrides, so this lookup must be explicit.
+ */
+export function resolveAssistantCommand(
+  commandOverride: string | undefined,
+  customCommands: Record<string, string>,
+  option: AssistantOption
+): string {
+  return commandOverride ?? customCommands[option.id] ?? option.command
+}
+
 export const tabCreate: CliCommand = {
   args: [],
   flags: [
     ...SHARED_FLAGS,
     {
-      description: 'assistant id (claude, codex, opencode, terminal, ...)',
+      description: 'assistant id (claude, codex, opencode, grok, terminal, ...)',
       kind: 'string',
       name: 'assistant',
     },
@@ -49,6 +81,17 @@ export const tabCreate: CliCommand = {
       kind: 'string',
       name: 'worktree',
     },
+    {
+      description: 'create a fresh worktree for this tab (optionally named: --new-worktree=<name>)',
+      kind: 'optional-string',
+      name: 'new-worktree',
+    },
+    { description: 'base ref for --new-worktree (default HEAD)', kind: 'string', name: 'base' },
+    {
+      description: 'branch for --new-worktree (default aimux/<name>)',
+      kind: 'string',
+      name: 'branch',
+    },
   ],
   group: 'tab',
   run: async (ctx) => {
@@ -56,7 +99,12 @@ export const tabCreate: CliCommand = {
     if (typeof assistantId !== 'string' || assistantId.length === 0) {
       throw new Error('--assistant is required')
     }
-    const options = getAllAssistantOptions({})
+    // Load the workspace's persisted customCommands so CLI-spawned tabs honor
+    // the same assistant commands the UI uses (e.g. skip-permissions flags), and
+    // so purely-custom assistant ids resolve. loadConfig degrades to {} on a
+    // missing/invalid config — no new failure mode.
+    const { customCommands } = loadConfig()
+    const options = getAllAssistantOptions(customCommands)
     const option = options.find((o) => o.id === assistantId)
     if (!option) {
       throw new Error(
@@ -77,10 +125,28 @@ export const tabCreate: CliCommand = {
       )
     }
 
-    const command = commandOverride ?? option.command
+    const command = resolveAssistantCommand(commandOverride, customCommands, option)
     const title = typeof ctx.args.flags.title === 'string' ? ctx.args.flags.title : option.label
     const cwdRaw = typeof ctx.args.flags.cwd === 'string' ? ctx.args.flags.cwd : undefined
-    const cwd = cwdRaw === undefined ? undefined : resolvePath(cwdRaw)
+    const tabId = createPrefixedId('tab')
+
+    // `--new-worktree[=<name>]`: create a fresh worktree and run the tab in it.
+    // A bare flag parses as `true` (name derived below); the `=` form names it.
+    const newWorktreeFlag = ctx.args.flags['new-worktree']
+    const newWorktree = newWorktreeFlag !== undefined
+    const worktreeFlag =
+      typeof ctx.args.flags.worktree === 'string' ? ctx.args.flags.worktree : undefined
+    const baseFlag = typeof ctx.args.flags.base === 'string' ? ctx.args.flags.base : undefined
+    const branchFlag = typeof ctx.args.flags.branch === 'string' ? ctx.args.flags.branch : undefined
+    if (newWorktree && worktreeFlag !== undefined) {
+      throw new Error('--new-worktree creates its own; use --worktree <id> to co-locate instead')
+    }
+    if (newWorktree && cwdRaw !== undefined) {
+      throw new Error('--new-worktree sets the cwd to the new worktree; drop --cwd')
+    }
+    if (!newWorktree && (baseFlag !== undefined || branchFlag !== undefined)) {
+      throw new Error('--base / --branch require --new-worktree (use `worktree create` otherwise)')
+    }
 
     const workspace = ctx.getWorkspace()
     const daemon = await ctx.getDaemon()
@@ -91,20 +157,42 @@ export const tabCreate: CliCommand = {
       )
     }
 
-    // Resolve worktreeId: explicit flag wins, otherwise the workspace's
-    // currently-active worktree, otherwise undefined (= no grouping).
-    const worktreeFlag =
-      typeof ctx.args.flags.worktree === 'string' ? ctx.args.flags.worktree : undefined
-    let worktreeId: string | undefined = worktreeFlag ?? workspace.activeWorktreeId
-    if (worktreeFlag !== undefined) {
-      const known = workspace.worktrees?.some((w) => w.id === worktreeFlag) ?? false
-      if (!known) {
-        const ids = workspace.worktrees?.map((w) => w.id).join(', ') ?? '(none)'
-        throw new Error(`unknown worktree id: ${worktreeFlag} (known: ${ids})`)
+    // Resolve the worktree the tab belongs to + its record (for the cwd default
+    // and the output). Three modes: create a fresh one, use an explicit id, or
+    // fall back to the workspace's active worktree.
+    let worktreeId: string | undefined
+    let worktreeRecord: { branch?: string; name?: string; path: string } | undefined
+    if (newWorktree) {
+      const worktreeName =
+        typeof newWorktreeFlag === 'string' && newWorktreeFlag !== ''
+          ? newWorktreeFlag
+          : `${assistantId}-${tabId.slice(-6)}`
+      const record = await createWorkspaceWorktree({
+        base: baseFlag ?? 'HEAD',
+        branch: branchFlag ?? `aimux/${worktreeName}`,
+        daemon,
+        name: worktreeName,
+        workspace,
+      })
+      worktreeId = record.id
+      worktreeRecord = record
+    } else {
+      worktreeId = worktreeFlag ?? workspace.activeWorktreeId
+      if (worktreeFlag !== undefined) {
+        const known = workspace.worktrees?.some((w) => w.id === worktreeFlag) ?? false
+        if (!known) {
+          const ids = workspace.worktrees?.map((w) => w.id).join(', ') ?? '(none)'
+          throw new Error(`unknown worktree id: ${worktreeFlag} (known: ${ids})`)
+        }
       }
-      worktreeId = worktreeFlag
+      worktreeRecord =
+        worktreeId !== undefined ? workspace.worktrees?.find((w) => w.id === worktreeId) : undefined
     }
 
+    // Default the PTY cwd to the resolved worktree's path so a worker spawned
+    // into a worktree actually runs inside it. An explicit --cwd always wins.
+    const cwd = resolveTabCwd(cwdRaw, worktreeRecord)
+
     // Thin-attach so we don't clobber the UI's dimensions on the same session.
     await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
 
@@ -113,7 +201,6 @@ export const tabCreate: CliCommand = {
     // assistant has no control for a requested dimension.
     const modelArgs = buildAssistantModelArgs(option, { effort, model })
     const args = [...baseArgs, ...modelArgs]
-    const tabId = createPrefixedId('tab')
 
     // cols/rows = 0 means "fall back to the session's last attached size" on
     // v11 daemons. Without that capability we have nothing reasonable to put
@@ -135,12 +222,16 @@ export const tabCreate: CliCommand = {
     const resolvedCommand = [executable, ...args].join(' ')
     writeJson({
       assistant: assistantId,
+      branch: worktreeRecord?.branch ?? null,
       command: resolvedCommand,
+      cwd: cwd ?? null,
       effort: effort ?? null,
       model: model ?? null,
+      name: worktreeRecord?.name ?? null,
+      path: worktreeRecord?.path ?? null,
       tabId,
       title,
-      worktreeId,
+      worktreeId: worktreeId ?? null,
     })
     return EXIT_OK
   },

package/src/cli/commands/tab/prompt-io.ts

@@ -17,6 +17,31 @@ import { bracketedPaste, notationToBytes } from '../../chord'
  */
 export const PASTE_SUBMIT_SETTLE_MS = 50
 
+/**
+ * Resolve prompt text from exactly one source — `--prompt-file`, `--stdin`, or
+ * a positional `[text]`. Requiring exactly one prevents an orchestrator from
+ * silently sending the wrong buffer when two are set (e.g. a stale positional
+ * plus a fresh `--prompt-file`). Used by `tab run`; `tab send` keeps its own
+ * looser guard (zero sources is valid there).
+ */
+export async function resolvePromptText(
+  promptFile: string | undefined,
+  fromStdin: boolean,
+  positionalText: string | undefined
+): Promise<string> {
+  const sources = [promptFile !== undefined, fromStdin, positionalText !== undefined].filter(
+    (present) => present
+  ).length
+  if (sources !== 1) {
+    throw new Error(
+      'provide exactly one prompt source: --prompt-file <f>, --stdin, or a [text] positional'
+    )
+  }
+  if (promptFile !== undefined) return Bun.file(promptFile).text()
+  if (fromStdin) return Bun.stdin.text()
+  return positionalText ?? ''
+}
+
 /**
  * Lower a chord/paste buffer of bytes into the string the protocol expects.
  * Every byte we emit is < 0x80 (control chars or printable ASCII), so a

package/src/cli/commands/tab/run.ts

@@ -7,7 +7,6 @@
  * timeout trips. Exactly one JSON object is emitted and the exit code encodes
  * the outcome, so a driver can branch without re-snapshotting the screen.
  */
-import type { QuestionKind } from '../../../state/types'
 import type { CliCommand } from '../../registry'
 
 import {
@@ -16,73 +15,9 @@ import {
   IPC_CAPABILITY_TURN_LIFECYCLE,
 } from '../../../ipc/protocol'
 import { SHARED_FLAGS } from '../../flags'
-import { EXIT_OK, EXIT_QUESTION, EXIT_RUNTIME, EXIT_TIMEOUT, writeJson } from '../../output'
-import { buildPromptPayload, writePromptPayload } from './prompt-io'
-
-/** Overall cap on a single turn — 15 min, long enough for a heavy build task. */
-const DEFAULT_TIMEOUT_MS = 900_000
-
-/**
- * The four terminal shapes of a `tab run`. Modelled as a discriminated union so
- * the JSON we emit and the exit code we return are derived from one value, and
- * so the outcome→exit mapping can be unit-tested without a live daemon.
- * `durationMs` is measured from prompt submit, not attach, so it reflects the
- * worker's think time rather than our connection overhead.
- */
-export type RunOutcome =
-  | { durationMs: number; outcome: 'completed' }
-  | { durationMs: number; error: string; outcome: 'error' }
-  | {
-      durationMs: number
-      kind: QuestionKind
-      options?: string[]
-      outcome: 'question'
-      question: string
-    }
-  | { durationMs: number; outcome: 'timeout' }
-
-/**
- * Map an outcome to its process exit code. Pure and total over the union so a
- * driver's `case $?` stays exhaustive: 0 completed, 10 question/permission
- * (worker is blocked and wants input), 3 the tab errored/exited, 124 we hit the
- * overall cap.
- */
-export function outcomeExitCode(outcome: RunOutcome): number {
-  switch (outcome.outcome) {
-    case 'completed':
-      return EXIT_OK
-    case 'question':
-      return EXIT_QUESTION
-    case 'error':
-      return EXIT_RUNTIME
-    case 'timeout':
-      return EXIT_TIMEOUT
-  }
-}
-
-/**
- * Resolve the prompt text from exactly one source. We require exactly one of
- * `--prompt-file`, `--stdin`, or the positional `[text]` so an orchestrator
- * never silently sends the wrong buffer when two sources are set (e.g. a stale
- * positional plus a fresh `--prompt-file`).
- */
-async function resolvePromptText(
-  promptFile: string | undefined,
-  fromStdin: boolean,
-  positionalText: string | undefined
-): Promise<string> {
-  const sources = [promptFile !== undefined, fromStdin, positionalText !== undefined].filter(
-    (present) => present
-  ).length
-  if (sources !== 1) {
-    throw new Error(
-      'provide exactly one prompt source: --prompt-file <f>, --stdin, or a [text] positional'
-    )
-  }
-  if (promptFile !== undefined) return Bun.file(promptFile).text()
-  if (fromStdin) return Bun.stdin.text()
-  return positionalText ?? ''
-}
+import { writeJson } from '../../output'
+import { awaitTurn, DEFAULT_TIMEOUT_MS, turnOutcomeExitCode } from './await-turn'
+import { buildPromptPayload, resolvePromptText, writePromptPayload } from './prompt-io'
 
 export const tabRun: CliCommand = {
   args: [{ name: 'tabId', required: true }, { name: 'text' }],
@@ -136,86 +71,20 @@ export const tabRun: CliCommand = {
 
     const payload = buildPromptPayload(text, false)
 
-    return new Promise<number>((resolve) => {
-      // Subscribe BEFORE writing: these events fire only on transitions, so a
-      // late subscription would race the worker starting its turn.
-      let start = Date.now()
-      // Uptake guard. The tab may sit `idle` from a prior turn; a stale
-      // `tabTurnComplete` (or the settle window closing on that old idle) must
-      // not read as "this turn completed". Only honour completion once we've
-      // seen the tab go `working` after our submit.
-      let sawWorking = false
-
-      const settle = (outcome: RunOutcome): void => {
-        cleanup()
-        writeJson(outcome)
-        resolve(outcomeExitCode(outcome))
-      }
-      const durationMs = (): number => Date.now() - start
-
-      const offStatus = daemon.on('tabStatus', (p) => {
-        if (p.tabId !== tabId) return
-        if (p.status === 'working') sawWorking = true
-      })
-      const offTurn = daemon.on('tabTurnComplete', (p) => {
-        if (p.tabId !== tabId) return
-        // Ignore end-of-turn until the worker actually started working, so a
-        // lingering pre-submit idle can't be mis-read as completion.
-        if (!sawWorking) return
-        settle({ durationMs: durationMs(), outcome: 'completed' })
-      })
-      const offQuestion = daemon.on('tabQuestion', (p) => {
-        if (p.tabId !== tabId) return
-        // A question is honoured immediately — it can legitimately arrive
-        // before `working` (the worker asks before doing anything).
-        settle({
-          durationMs: durationMs(),
-          kind: p.kind,
-          options: p.options,
-          outcome: 'question',
-          question: p.prompt,
-        })
-      })
-      const offExit = daemon.on('tabExit', (p) => {
-        if (p.tabId !== tabId) return
-        settle({ durationMs: durationMs(), error: `exit ${p.exitCode}`, outcome: 'error' })
-      })
-      const offError = daemon.on('tabError', (p) => {
-        if (p.tabId !== tabId) return
-        settle({ durationMs: durationMs(), error: p.message, outcome: 'error' })
-      })
-
-      const timer = setTimeout(() => {
-        settle({ durationMs: durationMs(), outcome: 'timeout' })
-      }, timeoutMs)
-
-      const cleanup = (): void => {
-        offStatus()
-        offTurn()
-        offQuestion()
-        offExit()
-        offError()
-        clearTimeout(timer)
-      }
-
-      // Submit after subscribing, then reset the clock so `durationMs` measures
-      // the worker's turn rather than our attach/write overhead. On a write
-      // failure the tab likely died — surface it as an error outcome rather
-      // than sitting idle until the timeout.
-      const submit = async (): Promise<void> => {
-        try {
-          await writePromptPayload(daemon, tabId, payload, appendEnter)
-          start = Date.now()
-        } catch (error) {
-          settle({
-            durationMs: durationMs(),
-            error: error instanceof Error ? error.message : String(error),
-            outcome: 'error',
-          })
-        }
-      }
-      void submit()
+    // Submit inside `onArmed` so subscriptions are live before the worker starts
+    // its turn; `assumeWorking: false` keeps the uptake guard, so a lingering
+    // pre-submit idle can't be misread as completion.
+    const outcome = await awaitTurn({
+      assumeWorking: false,
+      daemon,
+      onArmed: async () => {
+        await writePromptPayload(daemon, tabId, payload, appendEnter)
+      },
+      tabId,
+      timeoutMs,
     })
+    writeJson(outcome)
+    return turnOutcomeExitCode(outcome)
   },
   summary: 'Submit a prompt and block until the turn completes or the worker asks',
   verb: 'run',

package/src/cli/commands/tab/send.ts

@@ -23,6 +23,11 @@ export const tabSend: CliCommand = {
       kind: 'boolean',
       name: 'stdin',
     },
+    {
+      description: 'read the payload from this file instead of <text>',
+      kind: 'string',
+      name: 'prompt-file',
+    },
     {
       description:
         'after submitting, block until the tab transitions to working (uptake confirmed)',
@@ -44,6 +49,8 @@ export const tabSend: CliCommand = {
     }
 
     const fromStdin = ctx.args.flags.stdin === true
+    const promptFile =
+      typeof ctx.args.flags['prompt-file'] === 'string' ? ctx.args.flags['prompt-file'] : undefined
     const asKeys = ctx.args.flags.keys === true
     const appendEnter = ctx.args.flags.enter === true
     const awaitSubmit = ctx.args.flags['await-submit'] === true
@@ -60,7 +67,26 @@ export const tabSend: CliCommand = {
       throw new Error('--await-submit requires --enter')
     }
 
-    const text = fromStdin ? await Bun.stdin.text() : (ctx.args.positionals[1] ?? '')
+    // At most one payload source. Unlike `tab run`, zero sources is valid here
+    // (`tab send <tab> --enter` submits an empty line), so we only reject
+    // conflicting combinations rather than requiring exactly one.
+    if (promptFile !== undefined) {
+      if (fromStdin) throw new Error('--prompt-file cannot be combined with --stdin')
+      if (asKeys)
+        throw new Error('--prompt-file cannot be combined with --keys (chords go in <text>)')
+      if (ctx.args.positionals[1] !== undefined) {
+        throw new Error('--prompt-file cannot be combined with a <text> positional')
+      }
+    }
+
+    let text: string
+    if (promptFile !== undefined) {
+      text = await Bun.file(promptFile).text()
+    } else if (fromStdin) {
+      text = await Bun.stdin.text()
+    } else {
+      text = ctx.args.positionals[1] ?? ''
+    }
     if (asKeys && text === '') {
       throw new Error('--keys requires the chord notation as <text>')
     }

package/src/cli/commands/worktree/create-core.ts

@@ -0,0 +1,96 @@
+import type { SessionRecord, WorktreeRecord } from '../../../state/types'
+import type { DaemonClient } from '../../client/daemon-client'
+
+import { createGitWorktree, removeGitWorktree } from '../../../git/worktree'
+import { IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS } from '../../../ipc/protocol'
+import { createPrefixedId } from '../../../platform/id'
+import {
+  assertSafeAimuxWorktreePath,
+  ensureAimuxWorktreeRoot,
+  makeWorktreePath,
+} from '../../../platform/worktree-paths'
+
+export interface CreateWorktreeParams {
+  /** Base ref for the branch (callers default to 'HEAD'). */
+  base: string
+  /** Branch name (callers default to `aimux/<name>`). */
+  branch: string
+  daemon: DaemonClient
+  name: string
+  workspace: SessionRecord
+}
+
+/**
+ * Create a git worktree + its catalog record for a workspace. Shared by
+ * `worktree create` and `tab create --new-worktree`. Checks the daemon
+ * capability BEFORE touching disk, and rolls back the on-disk worktree if
+ * catalog registration fails (so `worktree list` never surfaces an orphan).
+ * Throws on any failure; returns the registered record on success.
+ */
+export async function createWorkspaceWorktree(
+  params: CreateWorktreeParams
+): Promise<WorktreeRecord> {
+  const { base, branch, daemon, name, workspace } = params
+
+  const primary = workspace.worktrees?.find((w) => w.source === 'primary')
+  if (!primary) {
+    throw new Error(
+      `workspace "${workspace.name}" has no primary worktree — set --project when creating it`
+    )
+  }
+
+  // Check the daemon's capability BEFORE mutating disk — otherwise a capability
+  // mismatch would leave a git worktree on disk with no catalog record.
+  if (!daemon.hasCapability(IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS)) {
+    throw new Error(
+      'daemon predates worktreeLifecycleEvents capability — restart aimux to pick up the new daemon'
+    )
+  }
+
+  const worktreeId = createPrefixedId('worktree')
+  const targetPath = makeWorktreePath({
+    repoRoot: primary.repoRoot,
+    worktreeId,
+    worktreeName: name,
+  })
+  await ensureAimuxWorktreeRoot()
+  await assertSafeAimuxWorktreePath(targetPath)
+
+  await createGitWorktree({
+    baseRef: base,
+    branchName: branch,
+    repoPath: primary.repoRoot,
+    targetPath,
+  })
+
+  const now = new Date().toISOString()
+  const record: WorktreeRecord = {
+    baseRef: base,
+    branch,
+    createdAt: now,
+    createdByAimux: true,
+    id: worktreeId,
+    name,
+    path: targetPath,
+    repoRoot: primary.repoRoot,
+    source: 'aimux-temp',
+    updatedAt: now,
+  }
+
+  try {
+    await daemon.expectOk('addWorktreeRecord', { sessionId: workspace.id, worktree: record })
+  } catch (error) {
+    // Catalog registration failed — roll back the on-disk worktree so
+    // `worktree list` doesn't perpetually surface an orphan. Swallow rollback
+    // errors: report the original failure, the real problem to surface.
+    try {
+      await removeGitWorktree({ force: true, repoPath: primary.repoRoot, targetPath })
+    } catch {
+      // Best-effort rollback; leave the git-side worktree if it can't be removed
+      // cleanly. `worktree list` will flag it as gitTracked with no catalog.
+    }
+    throw error
+  }
+
+  return record
+}

package/src/cli/commands/worktree/create.ts

@@ -1,16 +1,8 @@
-import type { WorktreeRecord } from '../../../state/types'
 import type { CliCommand } from '../../registry'
 
-import { createGitWorktree, removeGitWorktree } from '../../../git/worktree'
-import { IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS } from '../../../ipc/protocol'
-import { createPrefixedId } from '../../../platform/id'
-import {
-  assertSafeAimuxWorktreePath,
-  ensureAimuxWorktreeRoot,
-  makeWorktreePath,
-} from '../../../platform/worktree-paths'
 import { SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, writeJson } from '../../output'
+import { createWorkspaceWorktree } from './create-core'
 
 export const worktreeCreate: CliCommand = {
   args: [],
@@ -31,80 +23,15 @@ export const worktreeCreate: CliCommand = {
     const base = typeof ctx.args.flags.base === 'string' ? ctx.args.flags.base : 'HEAD'
 
     const workspace = ctx.getWorkspace()
-    const primary = workspace.worktrees?.find((w) => w.source === 'primary')
-    if (!primary) {
-      throw new Error(
-        `workspace "${workspace.name}" has no primary worktree — set --project when creating it`
-      )
-    }
-
-    // Check the daemon's capability BEFORE mutating disk — otherwise a
-    // capability mismatch would leave a git worktree on disk with no
-    // catalog record to track it.
     const daemon = await ctx.getDaemon()
-    if (!daemon.hasCapability(IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS)) {
-      throw new Error(
-        'daemon predates worktreeLifecycleEvents capability — restart aimux to pick up the new daemon'
-      )
-    }
-
-    const worktreeId = createPrefixedId('worktree')
-    const targetPath = makeWorktreePath({
-      repoRoot: primary.repoRoot,
-      worktreeId,
-      worktreeName: name,
-    })
-    await ensureAimuxWorktreeRoot()
-    await assertSafeAimuxWorktreePath(targetPath)
-
-    await createGitWorktree({
-      baseRef: base,
-      branchName: branch,
-      repoPath: primary.repoRoot,
-      targetPath,
-    })
-
-    const now = new Date().toISOString()
-    const record: WorktreeRecord = {
-      baseRef: base,
-      branch,
-      createdAt: now,
-      createdByAimux: true,
-      id: worktreeId,
-      name,
-      path: targetPath,
-      repoRoot: primary.repoRoot,
-      source: 'aimux-temp',
-      updatedAt: now,
-    }
-
-    try {
-      await daemon.expectOk('addWorktreeRecord', { sessionId: workspace.id, worktree: record })
-    } catch (error) {
-      // Catalog registration failed — roll back the on-disk worktree so
-      // `worktree list` doesn't perpetually surface an orphan. Swallow
-      // rollback errors: report the original failure, which is the real
-      // problem the operator needs to see.
-      try {
-        await removeGitWorktree({
-          force: true,
-          repoPath: primary.repoRoot,
-          targetPath,
-        })
-      } catch {
-        // Best-effort rollback; leave the git-side worktree if it can't be
-        // removed cleanly. `worktree list --workspace` will flag it as
-        // `gitTracked: true, catalog: no` on the next inspection.
-      }
-      throw error
-    }
+    const record = await createWorkspaceWorktree({ base, branch, daemon, name, workspace })
 
     writeJson({
-      branch,
-      id: worktreeId,
-      name,
-      path: targetPath,
-      repoRoot: primary.repoRoot,
+      branch: record.branch,
+      id: record.id,
+      name: record.name,
+      path: record.path,
+      repoRoot: record.repoRoot,
     })
     return EXIT_OK
   },

package/src/cli/flags.ts

@@ -6,7 +6,7 @@
 
 export interface FlagSpec {
   name: string
-  kind: 'string' | 'number' | 'boolean'
+  kind: 'string' | 'number' | 'boolean' | 'optional-string'
   description?: string
 }
 
@@ -59,6 +59,13 @@ export function parseArgs(
         flags[name] = true
         continue
       }
+      if (spec.kind === 'optional-string') {
+        // Value binds ONLY in the `=` form (`--flag=value`). A bare `--flag`
+        // must not swallow the next token (it may be a positional), so it
+        // parses as boolean `true`.
+        flags[name] = eq === -1 ? true : token.slice(eq + 1)
+        continue
+      }
       const raw = eq === -1 ? argv[++i] : token.slice(eq + 1)
       if (raw === undefined) {
         throw new CliUsageError(`flag --${name} requires a value`)

package/src/cli/index.ts

@@ -20,8 +20,8 @@ const EXIT_CODES_BLOCK = [
   '  2    usage error (bad flags, unknown command, missing argument)',
   '  3    runtime error (server replied with error, command failed)',
   '  4    daemon unreachable (socket missing and autostart failed)',
-  '  10   question (tab run: worker is blocked on a question/permission)',
-  '  124  timeout (tab wait, tab tail --timeout, workspace switch --wait)',
+  '  10   question (tab run / tab await: worker is blocked on a question/permission)',
+  '  124  timeout (tab run, tab await, tab wait, tab tail --timeout, workspace switch --wait)',
 ].join('\n')
 
 const OUTPUT_CONTRACT_BLOCK = [
@@ -52,6 +52,7 @@ function formatArgs(args: readonly ArgSpec[]): string {
 function flagValueHint(flag: FlagSpec): string {
   if (flag.kind === 'boolean') return ''
   if (flag.kind === 'number') return ' <n>'
+  if (flag.kind === 'optional-string') return `[=<${flag.name}>]`
   return ` <${flag.name}>`
 }
 

package/src/cli/registry.ts

@@ -1,6 +1,7 @@
 import type { CliContext } from './context'
 import type { ArgSpec, FlagSpec } from './flags'
 
+import { tabAwait } from './commands/tab/await'
 import { tabClose } from './commands/tab/close'
 import { tabCreate } from './commands/tab/create'
 import { tabFocus } from './commands/tab/focus'
@@ -33,6 +34,7 @@ export const COMMANDS: readonly CliCommand[] = [
   tabCreate,
   tabSend,
   tabRun,
+  tabAwait,
   tabFocus,
   tabClose,
   tabSnapshot,

package/src/config.ts

@@ -13,7 +13,14 @@ function migrateThemeId(value: unknown): ThemeId | undefined {
   return resolveLegacyThemeId(value)
 }
 
-export const CONFIG_PATH = `${getProfileConfigDir()}/aimux.json`
+/**
+ * Path to the active profile's config file, resolved at CALL time. It must not
+ * be a module-level constant: `runCli` applies `--profile` (via `AIMUX_PROFILE`)
+ * after this module is imported, so a frozen path would read the wrong profile.
+ */
+export function getConfigPath(): string {
+  return `${getProfileConfigDir()}/aimux.json`
+}
 
 export interface PersistedGitPane {
   diffModeRatio?: number
@@ -238,12 +245,13 @@ function isCustomCommandsRecord(value: unknown): value is Record<string, string>
 }
 
 export function loadConfigResult(): ConfigLoadResult {
+  const configPath = getConfigPath()
   try {
-    if (!existsSync(CONFIG_PATH)) {
+    if (!existsSync(configPath)) {
       return { config: DEFAULT_CONFIG, issues: [], source: 'defaults' }
     }
 
-    const raw = readFileSync(CONFIG_PATH, 'utf8')
+    const raw = readFileSync(configPath, 'utf8')
     const parsed = JSON.parse(raw) as {
       version?: number
       customCommands?: unknown
@@ -346,7 +354,7 @@ export function loadConfigResult(): ConfigLoadResult {
     const validWorktreeTemplates = parseWorktreeTemplates(parsed.worktreeTemplates, issues)
 
     if (issues.length > 0) {
-      logDebug('config.load.validationIssue', { issues, path: CONFIG_PATH })
+      logDebug('config.load.validationIssue', { issues, path: configPath })
     }
 
     return {
@@ -371,7 +379,7 @@ export function loadConfigResult(): ConfigLoadResult {
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
-    logDebug('config.load.error', { error: message, path: CONFIG_PATH })
+    logDebug('config.load.error', { error: message, path: configPath })
     return {
       config: DEFAULT_CONFIG,
       issues: [`failed to load config: ${message}`],
@@ -385,14 +393,15 @@ export function loadConfig(): AimuxConfig {
 }
 
 export function saveConfig(config: AimuxConfig): boolean {
+  const configPath = getConfigPath()
   try {
     mkdirSync(getProfileConfigDir(), { recursive: true })
-    writeFileSync(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`)
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`)
     return true
   } catch (error) {
     logDebug('config.save.error', {
       error: error instanceof Error ? error.message : String(error),
-      path: CONFIG_PATH,
+      path: configPath,
     })
     return false
   }

package/src/doctor.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs'
 
-import { CONFIG_PATH, loadConfigResult } from './config'
+import { getConfigPath, loadConfigResult } from './config'
 import { ASSISTANT_OPTIONS, isCommandAvailable, parseCommand } from './pty/command-registry'
 
 export interface DoctorCheck {
@@ -22,11 +22,12 @@ function getConfigDetails(configResult: ReturnType<typeof loadConfigResult>): st
     return configResult.issues.join('; ')
   }
 
-  if (existsSync(CONFIG_PATH)) {
-    return `loaded ${CONFIG_PATH}`
+  const configPath = getConfigPath()
+  if (existsSync(configPath)) {
+    return `loaded ${configPath}`
   }
 
-  return `using defaults (${CONFIG_PATH} not found)`
+  return `using defaults (${configPath} not found)`
 }
 
 function getAssistantDetails(

package/src/index.tsx

@@ -83,7 +83,7 @@ if (command === '--help' || command === '-h' || command === 'help') {
       '',
       'Common CLI verbs at a glance',
       '  aimux tab list                                     Enumerate tabs (+ activeTabId)',
-      '  aimux tab create --assistant <id> [--title …]      Spawn claude / codex / opencode / terminal / …',
+      '  aimux tab create --assistant <id> [--title …]      Spawn claude / codex / opencode / grok / terminal / …',
       '  aimux tab send <tabId> [text] [--enter|--keys|--stdin]  Type, chord, or paste into a tab',
       '  aimux tab focus <tabId>                            Bring a tab to the foreground',
       '  aimux tab close <tabId>                            Terminate a tab',

package/src/pty/assistant-question-extractor.ts

@@ -41,6 +41,7 @@ const PERMISSION_SIGNALS: readonly string[] = [
   '△ permission',
   'allow this',
   'approve',
+  'pprove', // Grok stylized plan approval "[ a ] pprove ..."
   'grant',
   'press enter to confirm',
 ]

package/src/pty/assistant-status-detector.ts

@@ -6,7 +6,7 @@
  * `src/detect.rs` in that repo.
  *
  * The detector classifies a terminal session as `working`, `waiting-input`,
- * or `idle`. Built-in CLIs (claude, codex, opencode) use per-CLI substring
+ * or `idle`. Built-in CLIs (claude, codex, opencode, grok) have dedicated classify* functions.
  * tables. Custom CLIs fall back to a generic heuristic that (a) recognises
  * common shells as always-idle and (b) uses pane-tail change velocity plus
  * generic y/n / confirm prompt patterns.
@@ -95,7 +95,7 @@ export class AssistantStatusDetector {
 export function extractTailLines(viewport: TerminalSnapshot, lineCount: number): string[] {
   const isScrolledToBottom = viewport.viewportY === viewport.baseY
   const lines = isScrolledToBottom ? viewport.lines : (viewport.tailLines ?? viewport.lines)
-  // Full-screen TUIs (claude, opencode) paint in the alternate buffer and
+  // Full-screen TUIs (claude, opencode, grok) paint in the alternate buffer and
   // often leave the last rows blank, putting their status bar higher up.
   // Skip trailing blank rows before taking the last `lineCount`.
   let end = lines.length
@@ -138,6 +138,8 @@ function classifyBuiltin(
       return classifyCodex(haystack)
     case 'opencode':
       return classifyOpencode(haystack)
+    case 'grok':
+      return classifyGrok(haystack, rawTail)
     default:
       return null
   }
@@ -212,6 +214,47 @@ function classifyOpencode(haystack: string): TabActivity {
   return 'idle'
 }
 
+function classifyGrok(haystack: string, _rawTail: string): TabActivity {
+  // Waiting for user decision / input (plan approval, Q&A, permissions, confirms).
+  // These are the distinctive Grok Build TUI states that must produce 'waiting-input'
+  // so the rest of the system (turn lifecycle, question events, UI chips, orchestrators)
+  // treats grok the same as claude/codex/opencode.
+  if (
+    haystack.includes('waiting on answers') ||
+    haystack.includes('pprove') || // stylized "[ a ] pprove [ c ] omment [ q ] uit plan"
+    haystack.includes('omment') ||
+    haystack.includes('uit plan') ||
+    (haystack.includes('approve') &&
+      (haystack.includes('comment') || haystack.includes('quit') || haystack.includes('plan'))) ||
+    haystack.includes('enter :select') ||
+    haystack.includes('enter to select') ||
+    haystack.includes('enter submit') ||
+    haystack.includes('do you want') ||
+    haystack.includes('would you like') ||
+    haystack.includes('permission required') ||
+    haystack.includes('permission to') ||
+    haystack.includes('approve?') ||
+    haystack.includes('allow?')
+  ) {
+    return 'waiting-input'
+  }
+
+  // Agent actively reasoning or executing (mirrors claude spinner + interrupt logic).
+  // "Thought for Xs" is the primary visible trace while Grok thinks/plans.
+  if (
+    haystack.includes('thought for') || // "Thought for 3.4s", etc.
+    haystack.includes('thinking…') ||
+    haystack.includes('thinking ...') ||
+    haystack.includes('esc to interrupt') ||
+    haystack.includes('esc interrupt') ||
+    haystack.includes('esc: interrupt')
+  ) {
+    return 'working'
+  }
+
+  return 'idle'
+}
+
 const GENERIC_WAITING_PATTERNS: string[] = [
   '[y/n]',
   '(y/n)',

package/src/pty/command-registry.ts

@@ -59,6 +59,17 @@ export const ASSISTANT_OPTIONS: AssistantOption[] = [
       buildModelArgs: (model) => ['--model', model],
     },
   },
+  {
+    command: 'grok',
+    description: 'xAI Grok Build CLI',
+    id: 'grok',
+    label: 'Grok',
+    model: {
+      // Grok supports -m (and likely --model) plus --effort (alias --reasoning-effort).
+      buildEffortArgs: (effort) => ['--effort', effort],
+      buildModelArgs: (model) => ['-m', model],
+    },
+  },
   {
     command: 'agy',
     description: 'Antigravity CLI',

package/src/state/types.ts

@@ -4,7 +4,13 @@ import type { ThemedToken } from 'shiki'
 import type { WorktreeTemplate } from '../config'
 import type { LayoutNode, SplitDirection } from './layout-tree'
 
-export type BuiltinAssistantId = 'claude' | 'codex' | 'opencode' | 'terminal' | 'antigravity'
+export type BuiltinAssistantId =
+  | 'claude'
+  | 'codex'
+  | 'opencode'
+  | 'grok'
+  | 'terminal'
+  | 'antigravity'
 
 export type AssistantId = BuiltinAssistantId | (string & {})