@brimveyn/aimux 1.19.3 → 1.19.5

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.5",
   "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.3",
     "@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