@brimveyn/aimux 1.19.7 → 1.20.2

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

@@ -1,26 +1,61 @@
 import { resolve as resolvePath } from 'node:path'
 
+import type { WorktreeRecord } from '../../../state/types'
+import type { CliContext } from '../../context'
 import type { CliCommand } from '../../registry'
 
 import { loadConfig } from '../../../config'
+import { removeGitWorktree } from '../../../git/worktree'
 import {
   IPC_CAPABILITY_CREATE_TAB_SIZE_FALLBACK,
+  IPC_CAPABILITY_LIST_TABS,
   IPC_CAPABILITY_THIN_ATTACH,
+  IPC_CAPABILITY_WORKER_METADATA,
 } from '../../../ipc/protocol'
 import { createPrefixedId } from '../../../platform/id'
+import { pruneEmptyWorktreeParent } from '../../../platform/worktree-paths'
 import {
   type AssistantOption,
   buildAssistantModelArgs,
   getAllAssistantOptions,
   parseCommand,
 } from '../../../pty/command-registry'
-import { SHARED_FLAGS } from '../../flags'
+import { CliUsageError, SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, writeJson } from '../../output'
 import { createWorkspaceWorktree } from '../worktree/create-core'
 
 const FALLBACK_COLS = 200
 const FALLBACK_ROWS = 60
 
+export interface CreateCliTabOptions {
+  assistantId: string
+  base?: string
+  branch?: string
+  commandOverride?: string
+  cwd?: string
+  effort?: string
+  model?: string
+  newWorktree?: boolean | string
+  title?: string
+  workerName?: string
+  worktreeId?: string
+}
+
+export interface CreateCliTabResult {
+  assistant: string
+  branch: string | null
+  command: string
+  cwd: string | null
+  effort: string | null
+  model: string | null
+  name: string | null
+  path: string | null
+  tabId: string
+  title: string
+  workerName: string | null
+  worktreeId: string | null
+}
+
 /**
  * Resolve the cwd a spawned tab should run in. Precedence: explicit `--cwd`
  * (resolved to absolute) > the resolved worktree's path > undefined (the
@@ -50,44 +85,250 @@ export function resolveAssistantCommand(
   return commandOverride ?? customCommands[option.id] ?? option.command
 }
 
+async function rollbackCreatedWorktree(
+  record: WorktreeRecord,
+  ctx: CliContext,
+  originalError: unknown
+): Promise<never> {
+  const daemon = await ctx.getDaemon()
+  const workspace = ctx.getWorkspace()
+  let rollbackError: unknown
+  try {
+    await removeGitWorktree({
+      force: true,
+      repoPath: record.repoRoot,
+      targetPath: record.path,
+    })
+    await pruneEmptyWorktreeParent(record.path)
+    await daemon.expectOk('removeWorktreeRecord', {
+      sessionId: workspace.id,
+      worktreeId: record.id,
+    })
+  } catch (error) {
+    rollbackError = error
+  }
+  const original = originalError instanceof Error ? originalError.message : String(originalError)
+  if (rollbackError === undefined) throw originalError
+  const rollback =
+    rollbackError instanceof Error ? rollbackError.message : JSON.stringify(rollbackError)
+  throw new Error(`${original}; rollback failed: ${rollback}`)
+}
+
+/**
+ * Create a tab without writing to stdout. Worker commands compose this helper
+ * with prompt dispatch/await while `tab create` remains a thin compatibility
+ * adapter. All validation and daemon attachment happen before a worktree is
+ * created; any later failure rolls the fresh worktree back.
+ */
+export async function createCliTab(
+  ctx: CliContext,
+  options: CreateCliTabOptions
+): Promise<CreateCliTabResult> {
+  const {
+    assistantId,
+    base,
+    branch,
+    commandOverride,
+    cwd: cwdRaw,
+    effort,
+    model,
+    newWorktree,
+    title: requestedTitle,
+    workerName,
+    worktreeId: requestedWorktreeId,
+  } = options
+  if (assistantId.length === 0) throw new CliUsageError('--assistant is required')
+  if (workerName !== undefined && workerName.trim().length === 0) {
+    throw new CliUsageError('--name must be a non-empty string')
+  }
+  if (commandOverride !== undefined && (model !== undefined || effort !== undefined)) {
+    throw new CliUsageError(
+      '--model / --effort cannot be combined with --command (bake them into --command)'
+    )
+  }
+
+  const createFreshWorktree = newWorktree !== undefined && newWorktree !== false
+  if (createFreshWorktree && requestedWorktreeId !== undefined) {
+    throw new CliUsageError(
+      '--new-worktree creates its own; use --worktree <id> to co-locate instead'
+    )
+  }
+  if (createFreshWorktree && cwdRaw !== undefined) {
+    throw new CliUsageError('--new-worktree sets the cwd to the new worktree; drop --cwd')
+  }
+  if (!createFreshWorktree && (base !== undefined || branch !== undefined)) {
+    throw new CliUsageError(
+      '--base / --branch require --new-worktree (use `worktree create` otherwise)'
+    )
+  }
+
+  // Resolve and validate the complete assistant invocation before touching git.
+  const { customCommands } = loadConfig()
+  const option = getAllAssistantOptions(customCommands).find((entry) => entry.id === assistantId)
+  if (!option) {
+    const known = getAllAssistantOptions(customCommands)
+      .map((entry) => entry.id)
+      .join(', ')
+    throw new CliUsageError(`unknown assistant: ${assistantId} (known: ${known})`)
+  }
+  const command = resolveAssistantCommand(commandOverride, customCommands, option)
+  const { args: baseArgs, executable } = parseCommand(command)
+  const args = [...baseArgs, ...buildAssistantModelArgs(option, { effort, model })]
+  const title = requestedTitle ?? option.label
+  const tabId = createPrefixedId('tab')
+
+  const workspace = ctx.getWorkspace()
+  const daemon = await ctx.getDaemon()
+  if (!daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH)) {
+    throw new Error(
+      'daemon predates thinAttach capability — restart aimux to pick up the new daemon'
+    )
+  }
+  if (workerName !== undefined && !daemon.hasCapability(IPC_CAPABILITY_WORKER_METADATA)) {
+    throw new Error(
+      'daemon predates workerMetadata capability — restart aimux to use worker commands'
+    )
+  }
+  if (workerName !== undefined) {
+    if (!daemon.hasCapability(IPC_CAPABILITY_LIST_TABS)) {
+      throw new Error('daemon cannot validate worker-name uniqueness — restart aimux')
+    }
+    const existing = await daemon.listTabs(workspace.id)
+    if (existing.tabs.some((tab) => tab.workerName === workerName)) {
+      throw new Error(`worker name already exists in workspace "${workspace.name}": ${workerName}`)
+    }
+  }
+
+  // Attach before creating a worktree so stale daemon/session failures have no
+  // git-side effect.
+  await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+
+  let worktreeId = requestedWorktreeId ?? workspace.activeWorktreeId
+  let worktreeRecord =
+    worktreeId !== undefined
+      ? workspace.worktrees?.find((entry) => entry.id === worktreeId)
+      : undefined
+  if (requestedWorktreeId !== undefined && worktreeRecord === undefined) {
+    const ids = workspace.worktrees?.map((entry) => entry.id).join(', ') ?? '(none)'
+    throw new Error(`unknown worktree id: ${requestedWorktreeId} (known: ${ids})`)
+  }
+
+  let createdWorktree: WorktreeRecord | undefined
+  if (createFreshWorktree) {
+    const worktreeName =
+      typeof newWorktree === 'string' && newWorktree !== ''
+        ? newWorktree
+        : `${assistantId}-${tabId.slice(-6)}`
+    createdWorktree = await createWorkspaceWorktree({
+      base: base ?? 'HEAD',
+      branch: branch ?? `aimux/${worktreeName}`,
+      daemon,
+      name: worktreeName,
+      workspace,
+    })
+    worktreeId = createdWorktree.id
+    worktreeRecord = createdWorktree
+  }
+
+  const cwd = resolveTabCwd(cwdRaw, worktreeRecord)
+  const useFallback = daemon.hasCapability(IPC_CAPABILITY_CREATE_TAB_SIZE_FALLBACK)
+  try {
+    await daemon.expectOk('createTab', {
+      args,
+      assistant: assistantId,
+      autoRenameCandidate: requestedTitle === undefined,
+      cols: useFallback ? 0 : FALLBACK_COLS,
+      command: executable,
+      cwd,
+      rows: useFallback ? 0 : FALLBACK_ROWS,
+      tabId,
+      title,
+      workerName,
+      worktreeId,
+    })
+  } catch (error) {
+    if (createdWorktree !== undefined) {
+      return rollbackCreatedWorktree(createdWorktree, ctx, error)
+    }
+    throw error
+  }
+
+  return {
+    assistant: assistantId,
+    branch: worktreeRecord?.branch ?? null,
+    command: [executable, ...args].join(' '),
+    cwd: cwd ?? null,
+    effort: effort ?? null,
+    model: model ?? null,
+    name: worktreeRecord?.name ?? null,
+    path: worktreeRecord?.path ?? null,
+    tabId,
+    title,
+    workerName: workerName ?? null,
+    worktreeId: worktreeId ?? null,
+  }
+}
+
 export const tabCreate: CliCommand = {
   args: [],
   flags: [
     ...SHARED_FLAGS,
     {
+      complete: { kind: 'dynamic', source: 'assistant' },
       description: 'assistant id (claude, codex, opencode, grok, kimi, terminal, ...)',
       kind: 'string',
       name: 'assistant',
     },
-    { description: 'tab title (defaults to assistant label)', kind: 'string', name: 'title' },
-    { description: 'cwd for the spawned PTY', kind: 'string', name: 'cwd' },
     {
+      complete: { kind: 'none' },
+      description: 'tab title (defaults to assistant label)',
+      kind: 'string',
+      name: 'title',
+    },
+    {
+      complete: { kind: 'file' },
+      description: 'cwd for the spawned PTY',
+      kind: 'string',
+      name: 'cwd',
+    },
+    {
+      complete: { kind: 'none' },
       description: 'explicit command (overrides the assistant default)',
       kind: 'string',
       name: 'command',
     },
     {
+      complete: { kind: 'none' },
       description: 'model for the worker (maps to the assistant’s model flag)',
       kind: 'string',
       name: 'model',
     },
     {
+      complete: { kind: 'none' },
       description: 'reasoning-effort level (maps to the assistant’s effort flag)',
       kind: 'string',
       name: 'effort',
     },
     {
+      complete: { kind: 'dynamic', source: 'worktree' },
       description: 'worktree id the tab belongs to (defaults to the workspace’s active worktree)',
       kind: 'string',
       name: 'worktree',
     },
     {
+      complete: { kind: 'none' },
       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' },
     {
+      complete: { kind: 'dynamic', source: 'git-ref' },
+      description: 'base ref for --new-worktree (default HEAD)',
+      kind: 'string',
+      name: 'base',
+    },
+    {
+      complete: { kind: 'none' },
       description: 'branch for --new-worktree (default aimux/<name>)',
       kind: 'string',
       name: 'branch',
@@ -97,143 +338,37 @@ export const tabCreate: CliCommand = {
   run: async (ctx) => {
     const assistantId = ctx.args.flags.assistant
     if (typeof assistantId !== 'string' || assistantId.length === 0) {
-      throw new Error('--assistant is required')
-    }
-    // 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(
-        `unknown assistant: ${assistantId} (known: ${options.map((o) => o.id).join(', ')})`
-      )
+      throw new CliUsageError('--assistant is required')
     }
     const commandOverride =
       typeof ctx.args.flags.command === 'string' ? ctx.args.flags.command : undefined
     const model = typeof ctx.args.flags.model === 'string' ? ctx.args.flags.model : undefined
     const effort = typeof ctx.args.flags.effort === 'string' ? ctx.args.flags.effort : undefined
 
-    // A full `--command` override owns the whole invocation, so `--model` /
-    // `--effort` (which only make sense as additions to the assistant default)
-    // would be ambiguous alongside it — reject rather than silently drop them.
-    if (commandOverride !== undefined && (model !== undefined || effort !== undefined)) {
-      throw new Error(
-        '--model / --effort cannot be combined with --command (bake them into --command)'
-      )
-    }
-
-    const command = resolveAssistantCommand(commandOverride, customCommands, option)
-    const title = typeof ctx.args.flags.title === 'string' ? ctx.args.flags.title : option.label
+    const title = typeof ctx.args.flags.title === 'string' ? ctx.args.flags.title : undefined
     const cwdRaw = typeof ctx.args.flags.cwd === 'string' ? ctx.args.flags.cwd : undefined
-    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 newWorktreeRaw = ctx.args.flags['new-worktree']
+    const newWorktreeFlag =
+      typeof newWorktreeRaw === 'string' || typeof newWorktreeRaw === 'boolean'
+        ? newWorktreeRaw
+        : 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()
-
-    if (!daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH)) {
-      throw new Error(
-        'daemon predates thinAttach capability — restart aimux to pick up the new daemon'
-      )
-    }
-
-    // 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})`)
-        }
-      }
-      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 })
-
-    const { args: baseArgs, executable } = parseCommand(command)
-    // Append the model/effort flags to the assistant default. Throws if the
-    // assistant has no control for a requested dimension.
-    const modelArgs = buildAssistantModelArgs(option, { effort, model })
-    const args = [...baseArgs, ...modelArgs]
-
-    // 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
-    // here (the CLI has no terminal of its own), so use a roomy fallback —
-    // PTYs are reflowable, so 200×60 won't break anything that adapts.
-    const useFallback = daemon.hasCapability(IPC_CAPABILITY_CREATE_TAB_SIZE_FALLBACK)
-    await daemon.expectOk('createTab', {
-      args,
-      assistant: assistantId,
-      autoRenameCandidate: ctx.args.flags.title === undefined,
-      cols: useFallback ? 0 : FALLBACK_COLS,
-      command: executable,
-      cwd,
-      rows: useFallback ? 0 : FALLBACK_ROWS,
-      tabId,
-      title,
-      worktreeId,
-    })
-
-    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,
+    const result = await createCliTab(ctx, {
+      assistantId,
+      base: baseFlag,
+      branch: branchFlag,
+      commandOverride,
+      cwd: cwdRaw,
+      effort,
+      model,
+      newWorktree: newWorktreeFlag,
       title,
-      worktreeId: worktreeId ?? null,
+      worktreeId: worktreeFlag,
     })
+    writeJson(result)
     return EXIT_OK
   },
   summary: 'Create a new tab in the active workspace',

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

@@ -5,7 +5,7 @@ import { SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, writeJson } from '../../output'
 
 export const tabFocus: CliCommand = {
-  args: [{ name: 'tabId', required: true }],
+  args: [{ complete: { kind: 'dynamic', source: 'tab' }, name: 'tabId', required: true }],
   flags: SHARED_FLAGS,
   group: 'tab',
   run: async (ctx) => {

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

@@ -6,6 +6,7 @@
 import type { DaemonClient } from '../../client/daemon-client'
 
 import { bracketedPaste, notationToBytes } from '../../chord'
+import { CliUsageError } from '../../flags'
 
 /**
  * Gap between the bracketed-paste write and the trailing carriage return when
@@ -33,7 +34,7 @@ export async function resolvePromptText(
     (present) => present
   ).length
   if (sources !== 1) {
-    throw new Error(
+    throw new CliUsageError(
       'provide exactly one prompt source: --prompt-file <f>, --stdin, or a [text] positional'
     )
   }
@@ -91,7 +92,12 @@ export async function writePromptPayload(
   payload: PromptPayload,
   appendEnter: boolean
 ): Promise<number> {
-  await daemon.expectOk('write', { data: payload.data, tabId })
+  // Skip a zero-length write: "submit only" (empty payload + --enter) is a
+  // legitimate operation, but a 0-byte write reaches the pty as an empty
+  // ArrayBufferView and surfaces a raw Bun ERR_INVALID_ARG_TYPE to the user.
+  if (payload.data !== '') {
+    await daemon.expectOk('write', { data: payload.data, tabId })
+  }
   let bytesWritten = Buffer.byteLength(payload.data, 'utf8')
   if (appendEnter) {
     // A bracketed paste swallows a same-burst `\r`, so settle first, then

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

@@ -20,10 +20,18 @@ 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' }],
+  args: [
+    { complete: { kind: 'dynamic', source: 'tab' }, name: 'tabId', required: true },
+    { complete: { kind: 'none' }, name: 'text' },
+  ],
   flags: [
     ...SHARED_FLAGS,
-    { description: 'read the prompt from this file', kind: 'string', name: 'prompt-file' },
+    {
+      complete: { kind: 'file' },
+      description: 'read the prompt from this file',
+      kind: 'string',
+      name: 'prompt-file',
+    },
     { description: 'read the prompt from stdin', kind: 'boolean', name: 'stdin' },
     {
       description: 'overall turn cap in milliseconds (default 900000 = 15 min)',

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

@@ -9,7 +9,10 @@ import { buildPromptPayload, writePromptPayload } from './prompt-io'
 const DEFAULT_AWAIT_TIMEOUT_MS = 15_000
 
 export const tabSend: CliCommand = {
-  args: [{ name: 'tabId', required: true }, { name: 'text' }],
+  args: [
+    { complete: { kind: 'dynamic', source: 'tab' }, name: 'tabId', required: true },
+    { complete: { kind: 'none' }, name: 'text' },
+  ],
   flags: [
     ...SHARED_FLAGS,
     { description: 'append \\r so the receiving CLI submits', kind: 'boolean', name: 'enter' },
@@ -24,6 +27,7 @@ export const tabSend: CliCommand = {
       name: 'stdin',
     },
     {
+      complete: { kind: 'file' },
       description: 'read the payload from this file instead of <text>',
       kind: 'string',
       name: 'prompt-file',
@@ -59,12 +63,13 @@ export const tabSend: CliCommand = {
         ? ctx.args.flags['await-timeout']
         : DEFAULT_AWAIT_TIMEOUT_MS
 
-    // Uptake only means something once we actually submit the prompt: the
-    // working transition is the receiving CLI accepting the Enter. Without
-    // --enter there is nothing to confirm, so fail loudly rather than block
-    // forever on a transition that can't come.
-    if (awaitSubmit && !appendEnter) {
-      throw new Error('--await-submit requires --enter')
+    // Uptake only means something once something submits: either the appended
+    // `\r` (--enter) or a chord that carries its own submit (--keys "<CR>",
+    // which is the recovery path for a prompt already sitting in a composer).
+    // Without one of those there is nothing to confirm, so fail loudly rather
+    // than block forever on a transition that can't come.
+    if (awaitSubmit && !appendEnter && !asKeys) {
+      throw new Error('--await-submit requires --enter or --keys (the chord carries the submit)')
     }
 
     // At most one payload source. Unlike `tab run`, zero sources is valid here

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

@@ -9,11 +9,12 @@ import { snapshotTailLines, snapshotToLines } from '../../snapshot-render'
 const RENDER_WAIT_MS = 500
 
 export const tabSnapshot: CliCommand = {
-  args: [{ name: 'tabId', required: true }],
+  args: [{ complete: { kind: 'dynamic', source: 'tab' }, name: 'tabId', required: true }],
   flags: [
     ...SHARED_FLAGS,
     { description: 'return only the last N non-blank lines', kind: 'number', name: 'tail' },
     {
+      complete: { kind: 'values', values: ['json', 'text'] },
       description: 'output format: json (default) or text (raw screen dump)',
       kind: 'string',
       name: 'format',

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

@@ -21,7 +21,7 @@ function toCursor(snapshot: TerminalSnapshot): Cursor {
 }
 
 export const tabTail: CliCommand = {
-  args: [{ name: 'tabId', required: true }],
+  args: [{ complete: { kind: 'dynamic', source: 'tab' }, name: 'tabId', required: true }],
   flags: [
     ...SHARED_FLAGS,
     {

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

@@ -12,10 +12,11 @@ function isTabActivity(value: string): value is TabActivity {
 }
 
 export const tabWait: CliCommand = {
-  args: [{ name: 'tabId', required: true }],
+  args: [{ complete: { kind: 'dynamic', source: 'tab' }, name: 'tabId', required: true }],
   flags: [
     ...SHARED_FLAGS,
     {
+      complete: { kind: 'values', values: ['idle', 'waiting-input', 'working'] },
       description: 'target activity (idle | working | waiting-input)',
       kind: 'string',
       name: 'status',

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

@@ -0,0 +1,34 @@
+import type { CliCommand } from '../../registry'
+
+import { SHARED_FLAGS } from '../../flags'
+import { writeJson } from '../../output'
+import { DEFAULT_TIMEOUT_MS } from '../tab/await-turn'
+import {
+  awaitExistingWorker,
+  resolveWorkerTarget,
+  workerEnvelope,
+  workerOutcomeExitCode,
+  workerView,
+} from './shared'
+
+export const workerAwait: CliCommand = {
+  args: [{ complete: { kind: 'dynamic', source: 'worker' }, name: 'worker', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    { description: 'overall turn cap in milliseconds', kind: 'number', name: 'timeout' },
+  ],
+  group: 'worker',
+  run: async (ctx) => {
+    const { tab, workspace } = await resolveWorkerTarget(ctx, ctx.args.positionals[0] ?? '')
+    const outcome = await awaitExistingWorker(
+      ctx,
+      workspace,
+      tab.id,
+      typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_TIMEOUT_MS
+    )
+    writeJson(workerEnvelope(workspace, workerView(workspace, tab), outcome))
+    return workerOutcomeExitCode(outcome)
+  },
+  summary: "Await an existing worker's in-flight turn",
+  verb: 'await',
+}