@brimveyn/aimux 1.20.1 → 1.20.2

package/src/cli/completion/plan.ts

@@ -0,0 +1,216 @@
+/**
+ * Pure completion planner. Given the shell's current words + cursor index it
+ * decides WHAT should be completed — never how, and never with I/O. Dynamic
+ * sources come back as a plan the caller resolves (see `sources.ts`), which
+ * keeps this whole file unit-testable and free of daemon/filesystem access.
+ *
+ * The candidate lists are derived from `COMMANDS`, the same registry that
+ * generates `--help`, so completion cannot drift from the documented CLI.
+ */
+
+import type { CompletionSource, DynamicCompletionSource, FlagSpec } from '../flags'
+
+import { COMMANDS, resolveCommand } from '../registry'
+
+export interface CompletionCandidate {
+  description?: string
+  value: string
+}
+
+export type CompletionPlan =
+  /** Ready-to-print candidates, already filtered and prefixed. */
+  | { candidates: CompletionCandidate[]; kind: 'candidates' }
+  /** Needs live state. `prefix` is re-applied to each resolved value. */
+  | { kind: 'dynamic'; prefix: string; source: DynamicCompletionSource; word: string }
+  /** Hand off to the shell's own filename completion. */
+  | { kind: 'files' }
+  /** Free text — offer nothing. */
+  | { kind: 'none' }
+
+const NONE: CompletionPlan = { kind: 'none' }
+
+/**
+ * Top-level (non-group) commands, mirroring the branches in `src/index.tsx`.
+ * `daemon` / `terminal-manager` / `__complete` are internal and stay hidden.
+ */
+export const TOP_LEVEL_COMMANDS: readonly CompletionCandidate[] = [
+  { description: 'Print setup diagnostics', value: 'doctor' },
+  { description: 'Self-update to the latest release', value: 'update' },
+  { description: 'Print the package version', value: 'version' },
+  { description: 'Restart the IPC daemon (PTYs survive)', value: 'restart-daemon' },
+  { description: 'Restart the terminal manager (kills PTYs)', value: 'restart-terminal-manager' },
+  { description: 'Print or install a shell completion script', value: 'completion' },
+  { description: 'Show CLI help', value: 'help' },
+]
+
+const COMPLETION_SUBCOMMANDS: readonly CompletionCandidate[] = [
+  { description: 'Print the bash completion script', value: 'bash' },
+  { description: 'Print the fish completion script', value: 'fish' },
+  { description: 'Print the zsh completion script', value: 'zsh' },
+  { description: 'Install the script for the detected shell', value: 'install' },
+]
+
+const GROUP_DESCRIPTIONS: Record<string, string> = {
+  tab: 'Drive individual tabs (create, send, snapshot, await)',
+  worker: 'Named agent workers — the preferred orchestration surface',
+  workspace: 'Workspaces (sessions) in the profile catalog',
+  worktree: 'Git worktrees attached to the active workspace',
+}
+
+function groupCandidates(): CompletionCandidate[] {
+  const seen = new Set<string>()
+  const candidates: CompletionCandidate[] = []
+  for (const command of COMMANDS) {
+    if (seen.has(command.group)) continue
+    seen.add(command.group)
+    candidates.push({ description: GROUP_DESCRIPTIONS[command.group], value: command.group })
+  }
+  return candidates
+}
+
+function filtered(candidates: readonly CompletionCandidate[], word: string): CompletionPlan {
+  const matches = candidates
+    .filter((candidate) => candidate.value.startsWith(word))
+    .map((candidate) => ({ ...candidate }))
+  return { candidates: matches, kind: 'candidates' }
+}
+
+function fromSource(
+  source: CompletionSource | undefined,
+  word: string,
+  prefix: string
+): CompletionPlan {
+  if (!source) return NONE
+  switch (source.kind) {
+    case 'dynamic':
+      return { kind: 'dynamic', prefix, source: source.source, word }
+    case 'file':
+      return { kind: 'files' }
+    case 'values': {
+      const matches = source.values
+        .filter((value) => value.startsWith(word))
+        .map((value) => ({ value: `${prefix}${value}` }))
+      return { candidates: matches, kind: 'candidates' }
+    }
+    // 'none' and any future kind fall through to no candidates.
+    default:
+      return NONE
+  }
+}
+
+interface TokenScan {
+  /** Set when the last token was a flag still waiting for its value. */
+  awaitingValueFor: FlagSpec | null
+  positionalCount: number
+  stoppedFlags: boolean
+  usedFlags: Set<string>
+}
+
+/**
+ * Walk the tokens BEFORE the cursor the way `parseArgs` would, but tolerant of
+ * anything malformed — a half-typed command line is the normal case here.
+ */
+function scanTokens(tokens: readonly string[], flags: readonly FlagSpec[]): TokenScan {
+  const byName = new Map(flags.map((flag) => [flag.name, flag]))
+  const scan: TokenScan = {
+    awaitingValueFor: null,
+    positionalCount: 0,
+    stoppedFlags: false,
+    usedFlags: new Set<string>(),
+  }
+
+  for (const token of tokens) {
+    if (scan.awaitingValueFor) {
+      scan.awaitingValueFor = null
+      continue
+    }
+    if (!scan.stoppedFlags && token === '--') {
+      scan.stoppedFlags = true
+      continue
+    }
+    if (!scan.stoppedFlags && token.startsWith('--')) {
+      const eq = token.indexOf('=')
+      const name = eq === -1 ? token.slice(2) : token.slice(2, eq)
+      scan.usedFlags.add(name)
+      const spec = byName.get(name)
+      // `optional-string` only ever binds via `=`, so a bare one never awaits.
+      if (spec && eq === -1 && (spec.kind === 'string' || spec.kind === 'number')) {
+        scan.awaitingValueFor = spec
+      }
+      continue
+    }
+    scan.positionalCount++
+  }
+
+  return scan
+}
+
+function planTopLevel(word: string): CompletionPlan {
+  if (word.startsWith('-')) {
+    return filtered(
+      [
+        { description: 'Show CLI help', value: '--help' },
+        { description: 'Print the package version', value: '--version' },
+      ],
+      word
+    )
+  }
+  return filtered([...groupCandidates(), ...TOP_LEVEL_COMMANDS], word)
+}
+
+/**
+ * @param words Full command line tokens, including the program name at index 0.
+ * @param cword Index into `words` of the token being completed.
+ */
+export function planCompletion(words: readonly string[], cword: number): CompletionPlan {
+  const index = Math.max(0, cword)
+  const word = words[index] ?? ''
+  const argIndex = index - 1
+  if (argIndex < 0) return NONE
+
+  const args = words.slice(1)
+  if (argIndex === 0) return planTopLevel(word)
+
+  const group = args[0] ?? ''
+
+  if (group === 'completion') {
+    return argIndex === 1 ? filtered(COMPLETION_SUBCOMMANDS, word) : NONE
+  }
+
+  const verbs = COMMANDS.filter((command) => command.group === group)
+  if (verbs.length === 0) return NONE
+
+  if (argIndex === 1) {
+    return filtered(
+      verbs.map((command) => ({ description: command.summary, value: command.verb })),
+      word
+    )
+  }
+
+  const command = resolveCommand(group, args[1] ?? '')
+  if (!command) return NONE
+
+  const scan = scanTokens(args.slice(2, argIndex), command.flags)
+
+  if (scan.awaitingValueFor) {
+    return fromSource(scan.awaitingValueFor.complete, word, '')
+  }
+
+  if (!scan.stoppedFlags && word.startsWith('--')) {
+    const eq = word.indexOf('=')
+    if (eq !== -1) {
+      const name = word.slice(2, eq)
+      const spec = command.flags.find((flag) => flag.name === name)
+      if (!spec || spec.kind === 'boolean') return NONE
+      return fromSource(spec.complete, word.slice(eq + 1), `--${name}=`)
+    }
+    return filtered(
+      command.flags
+        .filter((flag) => !scan.usedFlags.has(flag.name))
+        .map((flag) => ({ description: flag.description, value: `--${flag.name}` })),
+      word
+    )
+  }
+
+  return fromSource(command.args[scan.positionalCount]?.complete, word, '')
+}

package/src/cli/completion/scripts.ts

@@ -0,0 +1,147 @@
+/**
+ * Shell completion scripts.
+ *
+ * They are deliberately THIN: collect the current words, shell out to
+ * `aimux __complete`, render the reply. All real logic lives in TypeScript, so
+ * upgrading aimux upgrades completion behaviour without regenerating anything
+ * the user has installed.
+ *
+ * Reply protocol (`__complete` stdout):
+ *   value<TAB>description   … zero or more candidate lines
+ *   :list | :files | :none  … exactly one trailing directive line
+ *
+ * `:files` means "no candidates of ours — use your own filename completion".
+ */
+
+import { COMMANDS } from '../registry'
+
+export type SupportedShell = 'bash' | 'fish' | 'zsh'
+
+export const SUPPORTED_SHELLS: readonly SupportedShell[] = ['bash', 'fish', 'zsh']
+
+export const DIRECTIVE_LIST = ':list'
+export const DIRECTIVE_FILES = ':files'
+export const DIRECTIVE_NONE = ':none'
+
+export function isSupportedShell(value: string): value is SupportedShell {
+  return SUPPORTED_SHELLS.includes(value as SupportedShell)
+}
+
+/** Long flags that take a path — fish needs these declared up front. */
+function fileFlagNames(): string[] {
+  const names = new Set<string>()
+  for (const command of COMMANDS) {
+    for (const flag of command.flags) {
+      if (flag.complete?.kind === 'file') names.add(flag.name)
+    }
+  }
+  return [...names].sort()
+}
+
+function bashScript(command: string): string {
+  return `# aimux bash completion. Regenerate with: aimux completion bash
+_aimux_complete() {
+  local IFS=$'\\n'
+  local directive="${DIRECTIVE_LIST}"
+  local -a candidates=()
+  local line
+
+  while IFS= read -r line; do
+    case "$line" in
+      :*) directive="$line" ;;
+      "") ;;
+      *) candidates+=("\${line%%$'\\t'*}") ;;
+    esac
+  done < <(${command} __complete --no-descriptions --cword "$COMP_CWORD" -- "\${COMP_WORDS[@]}" 2>/dev/null)
+
+  if [[ "$directive" == "${DIRECTIVE_FILES}" ]]; then
+    # Let readline do filenames itself — it handles quoting and trailing slashes.
+    compopt -o default 2>/dev/null
+    COMPREPLY=()
+    return 0
+  fi
+
+  compopt +o default 2>/dev/null
+  if [[ "$directive" == "${DIRECTIVE_NONE}" ]]; then
+    COMPREPLY=()
+    return 0
+  fi
+
+  COMPREPLY=($(compgen -W "\${candidates[*]}" -- "\${COMP_WORDS[COMP_CWORD]}"))
+}
+
+complete -F _aimux_complete aimux
+`
+}
+
+function zshScript(command: string): string {
+  return `#compdef aimux
+# aimux zsh completion. Regenerate with: aimux completion zsh
+
+_aimux_complete() {
+  local -a candidates
+  local directive="${DIRECTIVE_LIST}"
+  local line
+
+  local -a reply_lines
+  reply_lines=("\${(@f)$(${command} __complete --cword $((CURRENT - 1)) -- "\${words[@]}" 2>/dev/null)}")
+
+  for line in "\${reply_lines[@]}"; do
+    case "$line" in
+      :*) directive="$line" ;;
+      "") ;;
+      # _describe takes "value:description"; the reply is tab separated.
+      *) candidates+=("\${line/$'\\t'/:}") ;;
+    esac
+  done
+
+  if [[ "$directive" == "${DIRECTIVE_FILES}" ]]; then
+    _files
+    return
+  fi
+  [[ "$directive" == "${DIRECTIVE_NONE}" ]] && return
+
+  _describe -t aimux 'aimux' candidates
+}
+
+compdef _aimux_complete aimux
+`
+}
+
+function fishScript(command: string): string {
+  const fileFlags = fileFlagNames()
+    .map((name) => `complete -c aimux -l ${name} -r -F`)
+    .join('\n')
+  return `# aimux fish completion. Regenerate with: aimux completion fish
+
+function __aimux_complete
+    # \`commandline -opc\` is every finished token (including "aimux"), so its
+    # count IS the 0-based index of the token being typed. An empty current
+    # token expands to nothing, which the resolver reads as "".
+    set -l tokens (commandline -opc)
+    set -l current (commandline -ct)
+    ${command} __complete --cword (count $tokens) -- $tokens $current 2>/dev/null |
+        string match --invert --regex '^:'
+end
+
+complete -c aimux -f -a '(__aimux_complete)'
+
+# Flags that take a path get fish's own file completion.
+${fileFlags}
+`
+}
+
+/**
+ * @param command How the script should invoke aimux. Override it in dev to
+ * point at a checkout (e.g. `bun run /path/to/aimux/src/index.tsx`).
+ */
+export function renderCompletionScript(shell: SupportedShell, command = 'aimux'): string {
+  switch (shell) {
+    case 'bash':
+      return bashScript(command)
+    case 'fish':
+      return fishScript(command)
+    case 'zsh':
+      return zshScript(command)
+  }
+}

package/src/cli/completion/sources.ts

@@ -0,0 +1,74 @@
+/**
+ * Dynamic completion sources — the half of completion that needs live state.
+ *
+ * Two hard rules, because this code runs on every TAB press:
+ *  1. Never block. Anything that could hang (a daemon round-trip) must be
+ *     wrapped in a deadline by its resolver.
+ *  2. Never fail loudly. A source that throws yields zero candidates; the
+ *     shell must never see a stack trace where a completion list belongs.
+ *
+ * Phase 1 implements only the sources that read local state (built-in
+ * assistants, the workspace catalog). Daemon-backed sources — tabs, workers,
+ * worktrees — and git refs return nothing until phase 2 wires them up.
+ */
+
+import type { DynamicCompletionSource } from '../flags'
+import type { CompletionCandidate } from './plan'
+
+import { ASSISTANT_OPTIONS } from '../../pty/command-registry'
+
+function assistantCandidates(): CompletionCandidate[] {
+  return ASSISTANT_OPTIONS.map((option) => ({
+    description: option.description,
+    value: option.id,
+  }))
+}
+
+async function workspaceCandidates(): Promise<CompletionCandidate[]> {
+  // Imported lazily: the session catalog pulls in config + state modules that
+  // the static-source paths (groups, verbs, flags) have no reason to load.
+  const { listWorkspaces } = await import('../client/workspace-resolver')
+  const sessions = listWorkspaces()
+  const nameCounts = new Map<string, number>()
+  for (const session of sessions) {
+    nameCounts.set(session.name, (nameCounts.get(session.name) ?? 0) + 1)
+  }
+  return sessions.map((session) =>
+    // Ambiguous names can't be resolved by `--workspace`, so offer the id.
+    (nameCounts.get(session.name) ?? 0) > 1
+      ? { description: session.name, value: session.id }
+      : { description: session.id, value: session.name }
+  )
+}
+
+async function resolveSource(source: DynamicCompletionSource): Promise<CompletionCandidate[]> {
+  switch (source) {
+    case 'assistant':
+      return assistantCandidates()
+    case 'workspace':
+      return await workspaceCandidates()
+    // Phase 2: 'tab' | 'worker' | 'worktree' need a daemon round-trip under a
+    // deadline; 'git-ref' needs a `git for-each-ref` in the workspace repo.
+    default:
+      return []
+  }
+}
+
+/**
+ * Resolve a dynamic source, filter by the partial word, and re-apply the
+ * prefix the planner stripped (e.g. `--workspace=`). Always resolves.
+ */
+export async function resolveDynamicCandidates(
+  source: DynamicCompletionSource,
+  word: string,
+  prefix: string
+): Promise<CompletionCandidate[]> {
+  try {
+    const candidates = await resolveSource(source)
+    return candidates
+      .filter((candidate) => candidate.value.startsWith(word))
+      .map((candidate) => ({ ...candidate, value: `${prefix}${candidate.value}` }))
+  } catch {
+    return []
+  }
+}

package/src/cli/context.ts

@@ -1,5 +1,6 @@
 import type { SessionRecord } from '../state/types'
 import type { DaemonClient } from './client/daemon-client'
+import type { WorkspaceOrigin } from './client/workspace-resolver'
 import type { ParsedArgs } from './flags'
 
 /**
@@ -13,4 +14,18 @@ export interface CliContext {
   getDaemon: () => Promise<DaemonClient>
   /** Resolved workspace, populated on first call to `workspace()`. */
   getWorkspace: () => SessionRecord
+  /**
+   * Every catalogued workspace. Commands that must answer "is my worker really
+   * gone, or did the active workspace move?" need the whole catalog, not just
+   * the resolved record. Optional so test fixtures can inject one.
+   */
+  getWorkspaces?: () => SessionRecord[]
+  /**
+   * Where `getWorkspace()` came from — `flag` (`--workspace`), `env`
+   * (`AIMUX_WORKSPACE`), or `active` (most recently opened session). Only
+   * `active` can drift under a command while the UI switches workspaces, so
+   * commands that must not follow the UI branch on this. Optional so test
+   * fixtures can build a minimal context.
+   */
+  getWorkspaceOrigin?: () => WorkspaceOrigin
 }

package/src/cli/flags.ts

@@ -4,15 +4,48 @@
  * and `--` to end flag parsing. Unknown flags produce a usage error.
  */
 
+/**
+ * A dynamic completion source — resolved at TAB time from live state (catalog
+ * file, config, or the daemon) rather than from a fixed list. Resolution is
+ * always best-effort: a source that can't be reached yields no candidates
+ * instead of blocking or erroring the shell.
+ */
+export type DynamicCompletionSource =
+  | 'assistant'
+  | 'git-ref'
+  | 'tab'
+  | 'worker'
+  | 'workspace'
+  | 'worktree'
+
+/**
+ * Where a flag value or positional draws its shell-completion candidates.
+ * Declared on the spec next to `description` so `--help` and completion are
+ * generated from one source and can never drift apart.
+ *
+ * - `values` — fixed vocabulary, zero I/O
+ * - `dynamic` — resolved from live state, best-effort
+ * - `file`  — hand off to the shell's own filename completion
+ * - `none`  — free text (prompts, models, branch names we can't enumerate)
+ */
+export type CompletionSource =
+  | { kind: 'dynamic'; source: DynamicCompletionSource }
+  | { kind: 'file' }
+  | { kind: 'none' }
+  | { kind: 'values'; values: readonly string[] }
+
 export interface FlagSpec {
   name: string
   kind: 'string' | 'number' | 'boolean' | 'optional-string'
   description?: string
+  /** Completion source for this flag's VALUE. Boolean flags take none. */
+  complete?: CompletionSource
 }
 
 export interface ArgSpec {
   name: string
   required?: boolean
+  complete?: CompletionSource
 }
 
 export interface ParsedArgs {
@@ -102,7 +135,17 @@ export function parseArgs(
  * consistency with future formats.
  */
 export const SHARED_FLAGS: readonly FlagSpec[] = [
-  { description: 'workspace id or name', kind: 'string', name: 'workspace' },
-  { description: 'runtime profile override (sets AIMUX_PROFILE)', kind: 'string', name: 'profile' },
+  {
+    complete: { kind: 'dynamic', source: 'workspace' },
+    description: 'workspace id or name',
+    kind: 'string',
+    name: 'workspace',
+  },
+  {
+    complete: { kind: 'none' },
+    description: 'runtime profile override (sets AIMUX_PROFILE)',
+    kind: 'string',
+    name: 'profile',
+  },
   { description: 'always-on JSON output (kept for consistency)', kind: 'boolean', name: 'json' },
 ]

package/src/cli/index.ts

@@ -2,7 +2,7 @@ import type { DaemonClient } from './client/daemon-client'
 import type { CliContext } from './context'
 
 import { connectToDaemon, DaemonUnreachableError } from './client/bootstrap'
-import { resolveWorkspace } from './client/workspace-resolver'
+import { listWorkspaces, resolveWorkspaceWithOrigin } from './client/workspace-resolver'
 import { type ArgSpec, CliUsageError, type FlagSpec, parseArgs, SHARED_FLAGS } from './flags'
 import {
   EXIT_DAEMON_UNREACHABLE,
@@ -21,6 +21,7 @@ const EXIT_CODES_BLOCK = [
   '  3    runtime error (server replied with error, command failed)',
   '  4    daemon unreachable (socket missing and autostart failed)',
   '  10   question (tab run / tab await: worker is blocked on a question/permission)',
+  '  11   pending submit (worker holds an unsubmitted prompt — see `worker submit`)',
   '  124  timeout (tab run, tab await, tab wait, tab tail --timeout, workspace switch --wait)',
 ].join('\n')
 
@@ -99,14 +100,20 @@ function printHelp(): void {
       '',
       'Env:',
       '  AIMUX_PROFILE                  Runtime profile (state dir, socket paths); --profile overrides.',
+      '  AIMUX_WORKSPACE                Pin the target workspace (id or name); --workspace overrides.',
       '',
       'Agent recipe:',
       '  # create an isolated named worker, dispatch, and await one structured outcome',
-      '  aimux worker run --name fixup --assistant claude "explain this repo"',
+      '  # --workspace pins the target repo so a UI workspace switch cannot redirect it',
+      '  aimux worker run --workspace myrepo --name fixup --assistant claude "explain this repo"',
       '',
       'Maintenance:',
       '  aimux doctor | update | restart-daemon | restart-terminal-manager | version',
       '',
+      'Shell completion:',
+      '  Installed automatically on first launch (AIMUX_NO_COMPLETION_INSTALL=1 opts out).',
+      '  aimux completion install | aimux completion <bash|zsh|fish>',
+      '',
     ].join('\n')
   )
 }
@@ -218,11 +225,18 @@ export async function runCli(argv: readonly string[]): Promise<number> {
 
   const state: {
     daemon: DaemonClient | null
-    workspace: ReturnType<typeof resolveWorkspace> | null
+    workspace: ReturnType<typeof resolveWorkspaceWithOrigin> | null
   } = {
     daemon: null,
     workspace: null,
   }
+  const resolveOnce = (): ReturnType<typeof resolveWorkspaceWithOrigin> => {
+    if (state.workspace) return state.workspace
+    const workspaceFlag =
+      typeof parsed.flags.workspace === 'string' ? parsed.flags.workspace : undefined
+    state.workspace = resolveWorkspaceWithOrigin(workspaceFlag)
+    return state.workspace
+  }
   const ctx: CliContext = {
     args: parsed,
     getDaemon: async () => {
@@ -230,13 +244,9 @@ export async function runCli(argv: readonly string[]): Promise<number> {
       state.daemon = await connectToDaemon()
       return state.daemon
     },
-    getWorkspace: () => {
-      if (state.workspace) return state.workspace
-      const workspaceFlag =
-        typeof parsed.flags.workspace === 'string' ? parsed.flags.workspace : undefined
-      state.workspace = resolveWorkspace(workspaceFlag)
-      return state.workspace
-    },
+    getWorkspace: () => resolveOnce().record,
+    getWorkspaceOrigin: () => resolveOnce().origin,
+    getWorkspaces: () => listWorkspaces(),
   }
 
   try {

package/src/cli/output.ts

@@ -23,10 +23,13 @@ export function writeError(message: string): void {
 //   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)
+//   11  pending submit (`worker run --detach`: prompt is in the composer but no
+//       turn started — recoverable with `worker submit`, unlike a real error)
 //   124 timeout (`tab wait`, `tab tail --timeout`, `workspace switch --wait`)
 export const EXIT_OK = 0
 export const EXIT_USAGE = 2
 export const EXIT_RUNTIME = 3
 export const EXIT_DAEMON_UNREACHABLE = 4
 export const EXIT_QUESTION = 10
+export const EXIT_PENDING_SUBMIT = 11
 export const EXIT_TIMEOUT = 124

package/src/cli/registry.ts

@@ -17,6 +17,7 @@ import { workerList } from './commands/worker/list'
 import { workerPrompt } from './commands/worker/prompt'
 import { workerRun } from './commands/worker/run'
 import { workerStop } from './commands/worker/stop'
+import { workerSubmit } from './commands/worker/submit'
 import { workspaceClose } from './commands/workspace/close'
 import { workspaceCreate } from './commands/workspace/create'
 import { workspaceList } from './commands/workspace/list'
@@ -56,6 +57,7 @@ export const COMMANDS: readonly CliCommand[] = [
   worktreeRemove,
   workerRun,
   workerPrompt,
+  workerSubmit,
   workerAwait,
   workerList,
   workerStop,

package/src/doctor.ts

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs'
 
+import { completionStatus } from './cli/completion/install'
 import { getConfigPath, loadConfigResult } from './config'
 import { ASSISTANT_OPTIONS, isCommandAvailable, parseCommand } from './pty/command-registry'
 
@@ -73,6 +74,9 @@ export function buildDoctorReport(): DoctorReport {
     ok: configResult.issues.length === 0,
   })
 
+  const completion = completionStatus()
+  checks.push({ details: completion.detail, name: 'completion', ok: completion.ok })
+
   for (const option of ASSISTANT_OPTIONS) {
     const configuredCommand = config.customCommands[option.id] ?? option.command
     const { args, executable } = parseCommand(configuredCommand)

package/src/git/worktree.ts

@@ -59,6 +59,16 @@ export async function listLocalBranches(cwd: string): Promise<string[]> {
     .filter((line) => line !== '')
 }
 
+// Resolve a ref to its SHA in a specific repository, or undefined when it does
+// not exist there. The repo argument matters more than it looks: the same ref
+// name ("main", "HEAD") resolves in almost every repo, so a caller that picked
+// the wrong repository gets a *successful* resolution and no signal at all.
+export async function resolveGitRef(repoPath: string, ref: string): Promise<string | undefined> {
+  const result = await $`git -C ${repoPath} rev-parse --verify --quiet ${ref}`.quiet().nothrow()
+  if (result.exitCode !== 0) return undefined
+  return result.text().trim() || undefined
+}
+
 export async function createGitWorktree({
   baseRef,
   branchName,
@@ -74,7 +84,11 @@ export async function createGitWorktree({
     .quiet()
     .nothrow()
   if (result.exitCode !== 0) {
-    throw new Error(result.stderr.toString().trim() || 'failed to create git worktree')
+    // Always name the repository. A bare "fatal: not a valid object name: 'X'"
+    // reads as a ref-resolution bug when the real cause is that git ran in a
+    // repository the caller did not mean to target.
+    const stderr = result.stderr.toString().trim()
+    throw new Error(`${stderr || 'failed to create git worktree'} (in ${repoPath})`)
   }
 }