@brimveyn/aimux 1.19.7 → 1.20.1

package/README.md

@@ -157,6 +157,8 @@ The help modal reflects the resolved keymap, so it includes your overrides.
 
 ```bash
 aimux
+aimux worker doctor
+aimux worker run --name investigate --assistant claude "inspect this repository"
 aimux version
 aimux doctor
 aimux update
@@ -166,6 +168,10 @@ aimux restart-terminal-manager
 
 See [`docs/reference/cli.md`](docs/reference/cli.md) for behavior details.
 
+For agent orchestration, prefer the named `aimux worker` commands. They combine
+isolated worktree creation, prompt dispatch, authoritative turn waiting, fleet
+inspection, and guarded cleanup without shell wrappers or `jq`.
+
 ## Runtime Model
 
 `aimux` is split into:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.19.7",
+  "version": "1.20.1",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode, Kimi side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",
@@ -34,6 +34,7 @@
   ],
   "files": [
     "src",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -65,7 +66,7 @@
     "bump:terminal_manager": "bun run scripts/bump-protocol.ts terminal-manager"
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.8.4",
+    "@brimveyn/aimux-config": "0.8.5",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
     "@resvg/resvg-wasm": "^2.6.2",

package/skills/aimux-orchestrator/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: aimux-orchestrator
+description: Orchestrate implementation plans with parallel Claude, Codex, OpenCode, Grok, or Kimi workers through the aimux worker CLI. Use when an agent must decompose a plan, launch isolated workers, supervise questions and failures, review each worker's diff and checks, integrate accepted work, and clean up safely.
+---
+
+# aimux Orchestrator
+
+Own the plan and quality gate. Let aimux own worker transport and lifecycle.
+
+## Preflight
+
+Run once:
+
+```bash
+aimux worker doctor
+aimux worker --help
+```
+
+Stop if the doctor reports missing worker capabilities, the wrong workspace, or
+an unavailable assistant. Restart/update aimux as instructed; do not fall back
+to screen scraping or the legacy shell wrappers.
+
+## Orchestration loop
+
+1. Parse the plan into independently reviewable units and dependencies.
+2. Record units in a ledger. Copy `assets/ledger.template.md` for multi-unit work.
+3. Select only units whose dependencies are accepted.
+4. Launch no more workers than you can review:
+
+```bash
+aimux worker run \
+  --name feat-auth \
+  --assistant claude \
+  --prompt-file /tmp/feat-auth.md \
+  --detach
+```
+
+5. Inspect the fleet with `aimux worker list`.
+6. Await a detached worker with `aimux worker await feat-auth`.
+7. If a worker asks a question, answer only when the plan already determines the
+   answer:
+
+```bash
+aimux worker prompt feat-auth --prompt-file /tmp/answer.md
+```
+
+Escalate design choices, irreversible operations, deployments, pushes,
+migrations, spending, and external communication to the human.
+
+8. Review the worktree path returned in the worker JSON. Read the diff and run
+   the repository's required tests, typecheck, lint, and build. Worker claims
+   are not evidence.
+9. Accept, request a precise correction with `worker prompt`, or escalate.
+10. After integration, close and clean up:
+
+```bash
+aimux worker stop feat-auth --cleanup-worktree
+```
+
+## Isolation
+
+`worker run` creates a fresh worktree by default. Keep that default when writes
+may overlap or scope is uncertain.
+
+- Use `--worktree <id>` only for workers intentionally sharing one review unit.
+- Use `--no-worktree` only for sequential work or provably disjoint writes in
+  the active tree.
+- Review co-located workers together because their diff is shared.
+
+## Dispatch rules
+
+- Give each worker one bounded unit with goal, scope, exclusions, acceptance
+  criteria, repository conventions, and required verification.
+- Read `references/prompts.md` when drafting task or correction prompts.
+- Use provider defaults unless the plan or user requires a model. Set
+  `--model`/`--effort` only when `worker doctor` says the assistant supports the
+  control.
+- Prefer `--prompt-file` for multiline prompts; it avoids shell quoting hazards.
+- Use `--detach` for parallel launch. Without it, `worker run` waits and returns
+  a completed/question/timeout/error outcome.
+
+## Quality and safety
+
+Read `references/review.md` before accepting the first unit.
+
+- `completed` means the turn ended, not that the change is correct.
+- Never accept a failing or unrun verification gate.
+- Cap correction attempts at three; then escalate with evidence.
+- Never use `--force` cleanup unless the human authorized discarding dirty work.
+- Keep the ledger truthful after every dispatch, outcome, review, and integration.
+
+The CLI is the command reference. Use `aimux worker <verb> --help` instead of
+copying flags or JSON shapes into this skill.

package/skills/aimux-orchestrator/assets/ledger.template.md

@@ -0,0 +1,18 @@
+# Orchestration ledger
+
+Base: `<branch / sha>`
+
+| unit | goal | deps | status  | worker | worktree / branch | attempts | review evidence |
+| ---- | ---- | ---- | ------- | ------ | ----------------- | -------: | --------------- |
+| 1.1  |      | —    | pending |        |                   |        0 |                 |
+
+Statuses: `pending`, `dispatched`, `in-review`, `needs-changes`, `accepted`,
+`blocked`, `escalated`.
+
+## Decisions
+
+- `<date>` — `<decision and reason>`
+
+## Human questions
+
+- [ ] `<unit>` — `<decision needed, evidence, and options>`

package/skills/aimux-orchestrator/references/prompts.md

@@ -0,0 +1,57 @@
+# Worker prompts
+
+## Task
+
+```markdown
+# Task: <id> — <title>
+
+## Goal
+
+<observable outcome>
+
+## Scope
+
+- In: <files or subsystem>
+- Out: <explicit exclusions>
+
+## Requirements
+
+1. <behavior>
+2. <edge case>
+
+## Acceptance
+
+- <machine-checkable criterion>
+
+## Verification
+
+Run the repository's tests, typecheck, lint, and build commands that apply.
+Report changed files, commands run, results, and remaining risks.
+```
+
+Tell the worker to read repository instructions before editing. Do not ask it to
+merge, push, deploy, or clean up its worktree.
+
+## Correction
+
+```markdown
+# Correction for <id>
+
+The review found:
+
+- <specific failing behavior with file/test evidence>
+
+Required change:
+
+- <bounded correction>
+
+Do not broaden scope. Re-run:
+
+- <exact verification commands>
+```
+
+## Answer
+
+Answer the exact question and restate any relevant boundary. If the question
+introduces a product decision or risky action not settled by the plan, escalate
+instead of improvising.

package/skills/aimux-orchestrator/references/review.md

@@ -0,0 +1,18 @@
+# Worker review gate
+
+Review inside the returned worktree path.
+
+1. Read repository instructions and the dispatched acceptance criteria.
+2. Inspect status and the complete diff against the unit's base.
+3. Confirm every changed hunk belongs to the requested scope.
+4. Check correctness, edge cases, error paths, tests, debug leftovers, secrets,
+   stubs, and repository conventions.
+5. Run the required test, typecheck, lint, format-check, and build commands
+   yourself.
+6. Record evidence in the ledger.
+
+Accept only when the behavior and verification pass. If a check cannot run,
+record why and escalate when it prevents a trustworthy decision.
+
+Request changes with concrete evidence: location, observed behavior, expected
+behavior, and the exact gate to rerun. Do not send a vague "fix the tests" prompt.

package/src/cli/client/daemon-client.ts

@@ -135,10 +135,26 @@ export class DaemonClient {
     return this.hello.capabilities
   }
 
+  getAppVersion(): string | null {
+    return this.hello.appVersion ?? null
+  }
+
   getSelectedVersion(): number {
     return this.hello.selectedVersion
   }
 
+  getProcessVersion(): string {
+    return this.hello.processVersion
+  }
+
+  getManagerCapabilities(): readonly string[] {
+    return this.hello.managerCapabilities ?? []
+  }
+
+  getManagerSelectedVersion(): number | null {
+    return this.hello.managerSelectedVersion ?? null
+  }
+
   private async send(request: ClientRequest): Promise<ServerResponse> {
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {

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

@@ -1,11 +1,16 @@
 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 {
@@ -14,13 +19,42 @@ import {
   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,6 +84,189 @@ 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 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: [
@@ -97,143 +314,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/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'
     )
   }