@brimveyn/aimux 1.20.1 → 1.20.3

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

@@ -1,13 +1,18 @@
 import type { CliCommand } from '../../registry'
 
 import { isGitWorktreeDirty, removeGitWorktree } from '../../../git/worktree'
-import { IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS } from '../../../ipc/protocol'
+import {
+  IPC_CAPABILITY_THIN_ATTACH,
+  IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS,
+} from '../../../ipc/protocol'
+import { pruneEmptyWorktreeParent } from '../../../platform/worktree-paths'
+import { workspaceIdentity } from '../../client/workspace-resolver'
 import { SHARED_FLAGS } from '../../flags'
-import { EXIT_OK, writeJson } from '../../output'
-import { resolveWorkerTab, WORKER_SCHEMA_VERSION, workerView } from './shared'
+import { EXIT_OK, EXIT_RUNTIME, writeJson } from '../../output'
+import { resolveWorkerTarget, WORKER_SCHEMA_VERSION, workerView } from './shared'
 
 export const workerStop: CliCommand = {
-  args: [{ name: 'worker', required: true }],
+  args: [{ complete: { kind: 'dynamic', source: 'worker' }, name: 'worker', required: true }],
   flags: [
     ...SHARED_FLAGS,
     {
@@ -19,10 +24,9 @@ export const workerStop: CliCommand = {
   ],
   group: 'worker',
   run: async (ctx) => {
-    const tab = await resolveWorkerTab(ctx, ctx.args.positionals[0] ?? '')
-    const worker = workerView(ctx, tab)
+    const { tab, workspace } = await resolveWorkerTarget(ctx, ctx.args.positionals[0] ?? '')
+    const worker = workerView(workspace, tab)
     const daemon = await ctx.getDaemon()
-    const workspace = ctx.getWorkspace()
     const cleanup = ctx.args.flags['cleanup-worktree'] === true
     const record =
       tab.worktreeId === undefined
@@ -50,7 +54,29 @@ export const workerStop: CliCommand = {
       }
     }
 
-    await daemon.expectOk('closeTab', { tabId: tab.id })
+    // `closeTab` is session-scoped on the daemon, so it fails with "No session
+    // attached" unless this connection has attached first. Every other worker
+    // verb thin-attaches; this one did not, which made teardown the one step of
+    // the documented lifecycle a headless orchestrator could not complete.
+    if (!daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH)) {
+      throw new Error(
+        'daemon predates thinAttach capability — restart aimux to pick up the new daemon'
+      )
+    }
+    await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+
+    // Teardown is two independent effects. Report them independently: a failed
+    // tab close must not strand a merged worktree on disk with no way to remove
+    // it through aimux (the alternative — a bare `git worktree remove` — desyncs
+    // the catalog from disk).
+    let closeError: string | undefined
+    try {
+      await daemon.expectOk('closeTab', { tabId: tab.id })
+    } catch (error) {
+      closeError = error instanceof Error ? error.message : String(error)
+      if (!cleanup) throw error
+    }
+
     let worktreeRemoved = false
     if (cleanup && record !== undefined) {
       await removeGitWorktree({
@@ -58,6 +84,7 @@ export const workerStop: CliCommand = {
         repoPath: record.repoRoot,
         targetPath: record.path,
       })
+      await pruneEmptyWorktreeParent(record.path)
       try {
         await daemon.expectOk('removeWorktreeRecord', {
           sessionId: workspace.id,
@@ -72,12 +99,14 @@ export const workerStop: CliCommand = {
       worktreeRemoved = true
     }
     writeJson({
-      closed: true,
+      closed: closeError === undefined,
+      ...(closeError === undefined ? {} : { closeError }),
       schemaVersion: WORKER_SCHEMA_VERSION,
       worker,
+      workspace: workspaceIdentity(workspace),
       worktreeRemoved,
     })
-    return EXIT_OK
+    return closeError === undefined ? EXIT_OK : EXIT_RUNTIME
   },
   summary: 'Stop a named worker and optionally clean up its worktree',
   verb: 'stop',

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

@@ -0,0 +1,40 @@
+import type { CliCommand } from '../../registry'
+
+import { SHARED_FLAGS } from '../../flags'
+import { writeJson } from '../../output'
+import {
+  DETACH_UPTAKE_TIMEOUT_MS,
+  resolveWorkerTarget,
+  submitWorkerPrompt,
+  workerEnvelope,
+  workerOutcomeExitCode,
+  workerView,
+} from './shared'
+
+export const workerSubmit: CliCommand = {
+  args: [{ complete: { kind: 'dynamic', source: 'worker' }, name: 'worker', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    {
+      description: 'milliseconds to wait for the submit→working confirmation (default 15000)',
+      kind: 'number',
+      name: 'uptake-timeout',
+    },
+  ],
+  group: 'worker',
+  run: async (ctx) => {
+    const { tab, workspace } = await resolveWorkerTarget(ctx, ctx.args.positionals[0] ?? '')
+    const outcome = await submitWorkerPrompt(
+      ctx,
+      workspace,
+      tab.id,
+      typeof ctx.args.flags['uptake-timeout'] === 'number'
+        ? ctx.args.flags['uptake-timeout']
+        : DETACH_UPTAKE_TIMEOUT_MS
+    )
+    writeJson(workerEnvelope(workspace, workerView(workspace, tab), outcome))
+    return workerOutcomeExitCode(outcome)
+  },
+  summary: 'Submit a prompt already sitting in a worker composer and confirm uptake',
+  verb: 'submit',
+}

package/src/cli/commands/workspace/close.ts

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

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

@@ -9,10 +9,11 @@ import { EXIT_OK, EXIT_TIMEOUT, writeJson } from '../../output'
 const DEFAULT_WAIT_TIMEOUT_MS = 30_000
 
 export const workspaceCreate: CliCommand = {
-  args: [{ name: 'name', required: true }],
+  args: [{ complete: { kind: 'none' }, name: 'name', required: true }],
   flags: [
     ...SHARED_FLAGS,
     {
+      complete: { kind: 'file' },
       description: 'project path to associate with the workspace',
       kind: 'string',
       name: 'project',

package/src/cli/commands/workspace/switch.ts

@@ -8,7 +8,7 @@ import { EXIT_OK, EXIT_TIMEOUT, writeJson } from '../../output'
 const DEFAULT_WAIT_TIMEOUT_MS = 30_000
 
 export const workspaceSwitch: CliCommand = {
-  args: [{ name: 'workspace', required: true }],
+  args: [{ complete: { kind: 'dynamic', source: 'workspace' }, name: 'workspace', required: true }],
   flags: [
     ...SHARED_FLAGS,
     {

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

@@ -1,13 +1,14 @@
 import type { SessionRecord, WorktreeRecord } from '../../../state/types'
 import type { DaemonClient } from '../../client/daemon-client'
 
-import { createGitWorktree, removeGitWorktree } from '../../../git/worktree'
+import { createGitWorktree, removeGitWorktree, resolveGitRef } from '../../../git/worktree'
 import { IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS } from '../../../ipc/protocol'
 import { createPrefixedId } from '../../../platform/id'
 import {
   assertSafeAimuxWorktreePath,
   ensureAimuxWorktreeRoot,
   makeWorktreePath,
+  pruneEmptyWorktreeParent,
 } from '../../../platform/worktree-paths'
 
 export interface CreateWorktreeParams {
@@ -47,6 +48,17 @@ export async function createWorkspaceWorktree(
     )
   }
 
+  // Verify the base ref in the REPO WE ARE ABOUT TO USE, before touching disk.
+  // The workspace decides the repo, so a caller who believes it is orchestrating
+  // project A while the resolved workspace points at project B would otherwise
+  // get either a confusing bare git error or — when the ref exists in both repos
+  // — a silent success in the wrong project.
+  if ((await resolveGitRef(primary.repoRoot, base)) === undefined) {
+    throw new Error(
+      `base ref "${base}" does not exist in ${primary.repoRoot} (workspace "${workspace.name}") — check that this is the repository you meant`
+    )
+  }
+
   const worktreeId = createPrefixedId('worktree')
   const targetPath = makeWorktreePath({
     repoRoot: primary.repoRoot,
@@ -56,12 +68,19 @@ export async function createWorkspaceWorktree(
   await ensureAimuxWorktreeRoot()
   await assertSafeAimuxWorktreePath(targetPath)
 
-  await createGitWorktree({
-    baseRef: base,
-    branchName: branch,
-    repoPath: primary.repoRoot,
-    targetPath,
-  })
+  try {
+    await createGitWorktree({
+      baseRef: base,
+      branchName: branch,
+      repoPath: primary.repoRoot,
+      targetPath,
+    })
+  } catch (error) {
+    // `assertSafeAimuxWorktreePath` had to mkdir the repo-scoped parent for git;
+    // a failed creation must not leave that directory behind.
+    await pruneEmptyWorktreeParent(targetPath)
+    throw error
+  }
 
   const now = new Date().toISOString()
   const record: WorktreeRecord = {
@@ -85,6 +104,7 @@ export async function createWorkspaceWorktree(
     // errors: report the original failure, the real problem to surface.
     try {
       await removeGitWorktree({ force: true, repoPath: primary.repoRoot, targetPath })
+      await pruneEmptyWorktreeParent(targetPath)
     } catch {
       // Best-effort rollback; leave the git-side worktree if it can't be removed
       // cleanly. `worktree list` will flag it as gitTracked with no catalog.

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

@@ -8,9 +8,24 @@ export const worktreeCreate: CliCommand = {
   args: [],
   flags: [
     ...SHARED_FLAGS,
-    { description: 'display name for the new worktree', kind: 'string', name: 'name' },
-    { description: 'branch name (defaults to aimux/<name>)', kind: 'string', name: 'branch' },
-    { description: 'base ref for the branch (defaults to HEAD)', kind: 'string', name: 'base' },
+    {
+      complete: { kind: 'none' },
+      description: 'display name for the new worktree',
+      kind: 'string',
+      name: 'name',
+    },
+    {
+      complete: { kind: 'none' },
+      description: 'branch name (defaults to aimux/<name>)',
+      kind: 'string',
+      name: 'branch',
+    },
+    {
+      complete: { kind: 'dynamic', source: 'git-ref' },
+      description: 'base ref for the branch (defaults to HEAD)',
+      kind: 'string',
+      name: 'base',
+    },
   ],
   group: 'worktree',
   run: async (ctx) => {

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

@@ -5,11 +5,12 @@ import {
   IPC_CAPABILITY_LIST_TABS,
   IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS,
 } from '../../../ipc/protocol'
+import { pruneEmptyWorktreeParent } from '../../../platform/worktree-paths'
 import { SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, writeJson } from '../../output'
 
 export const worktreeRemove: CliCommand = {
-  args: [{ name: 'worktree', required: true }],
+  args: [{ complete: { kind: 'dynamic', source: 'worktree' }, name: 'worktree', required: true }],
   flags: [
     ...SHARED_FLAGS,
     { description: 'pass --force to git worktree remove', kind: 'boolean', name: 'force' },
@@ -59,6 +60,7 @@ export const worktreeRemove: CliCommand = {
     // All capability and liveness checks happen before touching git. If git
     // refuses a dirty worktree the catalog remains unchanged.
     await removeGitWorktree({ force, repoPath: primary.repoRoot, targetPath: worktree.path })
+    await pruneEmptyWorktreeParent(worktree.path)
     try {
       await daemon.expectOk('removeWorktreeRecord', {
         sessionId: workspace.id,

package/src/cli/completion/entry.ts

@@ -0,0 +1,181 @@
+/**
+ * Entry points for the two completion-facing commands:
+ *
+ *   aimux completion <bash|zsh|fish>   print the script
+ *   aimux completion install [--shell] write it to the conventional location
+ *   aimux __complete --cword N -- …    resolve one TAB press (hidden)
+ *
+ * `__complete` runs on every TAB, so this module's static import graph must
+ * stay tiny — no daemon client, no UI. See `test/unit/cli-completion-graph`.
+ */
+
+import { EXIT_OK, EXIT_USAGE, writeError } from '../output'
+import { detectShell, installCompletionScript, shellConfigHint } from './install'
+import { type CompletionPlan, planCompletion } from './plan'
+import {
+  DIRECTIVE_FILES,
+  DIRECTIVE_LIST,
+  DIRECTIVE_NONE,
+  isSupportedShell,
+  renderCompletionScript,
+  SUPPORTED_SHELLS,
+  type SupportedShell,
+} from './scripts'
+
+interface CompleteRequest {
+  cword: number
+  descriptions: boolean
+  words: string[]
+}
+
+/**
+ * Hand-rolled parser rather than `parseArgs`: `__complete` must never fail
+ * with a usage error — a malformed request yields an empty completion, not a
+ * message printed into the user's prompt.
+ */
+function parseCompleteRequest(argv: readonly string[]): CompleteRequest {
+  const request: CompleteRequest = { cword: 0, descriptions: true, words: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]
+    if (token === '--cword') {
+      const value = Number(argv[++i])
+      request.cword = Number.isFinite(value) ? value : 0
+      continue
+    }
+    if (token === '--no-descriptions') {
+      request.descriptions = false
+      continue
+    }
+    if (token === '--') {
+      request.words = argv.slice(i + 1) as string[]
+      break
+    }
+  }
+  return request
+}
+
+function renderCandidates(
+  candidates: readonly { description?: string; value: string }[],
+  descriptions: boolean
+): string {
+  return candidates
+    .map((candidate) => {
+      const description = candidate.description ?? ''
+      if (!descriptions || description === '') return candidate.value
+      // One tab, no newlines: every shell splits the reply on those.
+      return `${candidate.value}\t${description.replaceAll(/\s+/g, ' ')}`
+    })
+    .join('\n')
+}
+
+async function resolvePlan(plan: CompletionPlan, descriptions: boolean): Promise<string> {
+  switch (plan.kind) {
+    case 'candidates': {
+      if (plan.candidates.length === 0) return DIRECTIVE_NONE
+      return `${renderCandidates(plan.candidates, descriptions)}\n${DIRECTIVE_LIST}`
+    }
+    case 'dynamic': {
+      const { resolveDynamicCandidates } = await import('./sources')
+      const candidates = await resolveDynamicCandidates(plan.source, plan.word, plan.prefix)
+      if (candidates.length === 0) return DIRECTIVE_NONE
+      return `${renderCandidates(candidates, descriptions)}\n${DIRECTIVE_LIST}`
+    }
+    case 'files':
+      return DIRECTIVE_FILES
+    case 'none':
+      return DIRECTIVE_NONE
+  }
+}
+
+/** Resolve one TAB press. Always exits 0 — a shell is listening, not a human. */
+export async function runComplete(argv: readonly string[]): Promise<number> {
+  try {
+    const request = parseCompleteRequest(argv)
+    const plan = planCompletion(request.words, request.cword)
+    process.stdout.write(`${await resolvePlan(plan, request.descriptions)}\n`)
+  } catch {
+    process.stdout.write(`${DIRECTIVE_NONE}\n`)
+  }
+  return EXIT_OK
+}
+
+function printCompletionHelp(): void {
+  process.stdout.write(
+    [
+      'aimux completion — shell tab completion',
+      '',
+      'Usage:',
+      '  aimux completion <bash|zsh|fish>     Print the completion script',
+      '  aimux completion install             Install it for the detected shell',
+      '',
+      'Flags:',
+      '  --shell <bash|zsh|fish>        Override shell detection (install)',
+      '  --command <invocation>         How the script should call aimux',
+      '                                 (dev: "bun run /path/to/src/index.tsx")',
+      '',
+      'aimux installs completion for your shell automatically on first launch.',
+      'Set AIMUX_NO_COMPLETION_INSTALL=1 to opt out.',
+      '',
+    ].join('\n')
+  )
+}
+
+function flagValue(argv: readonly string[], name: string): string | undefined {
+  const index = argv.indexOf(`--${name}`)
+  if (index !== -1) return argv[index + 1]
+  const inline = argv.find((token) => token.startsWith(`--${name}=`))
+  return inline?.slice(name.length + 3)
+}
+
+/** `aimux completion …` — print or install a script. */
+export function runCompletion(argv: readonly string[]): number {
+  const subcommand = argv[0] ?? ''
+  const command = flagValue(argv, 'command')
+
+  if (subcommand === '' || subcommand === '--help' || subcommand === '-h') {
+    printCompletionHelp()
+    return subcommand === '' ? EXIT_USAGE : EXIT_OK
+  }
+
+  if (isSupportedShell(subcommand)) {
+    process.stdout.write(renderCompletionScript(subcommand, command))
+    return EXIT_OK
+  }
+
+  if (subcommand !== 'install') {
+    writeError(`unknown completion target: ${subcommand}`)
+    printCompletionHelp()
+    return EXIT_USAGE
+  }
+
+  const requested = flagValue(argv, 'shell')
+  let shell: SupportedShell | null
+  if (requested === undefined) {
+    shell = detectShell()
+  } else if (isSupportedShell(requested)) {
+    shell = requested
+  } else {
+    writeError(`unsupported shell: ${requested} (supported: ${SUPPORTED_SHELLS.join(', ')})`)
+    return EXIT_USAGE
+  }
+
+  if (shell === null) {
+    writeError(
+      `could not detect your shell from $SHELL — pass --shell <${SUPPORTED_SHELLS.join('|')}>`
+    )
+    return EXIT_USAGE
+  }
+
+  try {
+    const result = installCompletionScript(shell, command)
+    process.stdout.write(`installed ${result.shell} completion → ${result.path}\n`)
+    const hint = shellConfigHint(result)
+    if (hint !== '') process.stdout.write(`${hint}\n`)
+    process.stdout.write('restart your shell (or start a new one) to pick it up\n')
+    return EXIT_OK
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    writeError(`completion install failed: ${message}`)
+    return EXIT_USAGE
+  }
+}

package/src/cli/completion/install.ts

@@ -0,0 +1,222 @@
+/**
+ * Installing the completion script — on demand (`aimux completion install`)
+ * and automatically on first TUI launch.
+ *
+ * Auto-install is best-effort and silent: it drops ONE file in the shell's
+ * conventional completions directory and never edits a dotfile. When the
+ * chosen directory isn't guaranteed to be picked up (zsh `$fpath`), we report
+ * `pendingShellConfig` so the caller can print the one-line fix instead of
+ * silently rewriting the user's shell config.
+ */
+
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+
+import { version } from '../../../package.json'
+import { logDebug } from '../../debug/input-log'
+import { getConfigProfilesRootDir } from '../../profile-paths'
+import { isSupportedShell, renderCompletionScript, type SupportedShell } from './scripts'
+
+export interface InstallResult {
+  path: string
+  /** True when the file is written but the shell won't load it unaided. */
+  pendingShellConfig: boolean
+  shell: SupportedShell
+}
+
+interface InstallMarker {
+  installedAt: string
+  path: string
+  shell: SupportedShell
+  version: string
+}
+
+function home(): string {
+  const fromEnv = process.env.HOME
+  return fromEnv != null && fromEnv !== '' ? fromEnv : homedir()
+}
+
+function dataHome(): string {
+  const xdg = process.env.XDG_DATA_HOME
+  return xdg != null && xdg !== '' ? xdg : join(home(), '.local', 'share')
+}
+
+function configHome(): string {
+  const xdg = process.env.XDG_CONFIG_HOME
+  return xdg != null && xdg !== '' ? xdg : join(home(), '.config')
+}
+
+/** Detect the user's shell from `$SHELL`. Returns null for anything exotic. */
+export function detectShell(): SupportedShell | null {
+  const shellPath = process.env.SHELL
+  if (shellPath == null || shellPath === '') return null
+  const name = basename(shellPath)
+  return isSupportedShell(name) ? name : null
+}
+
+function isWritableDir(dir: string): boolean {
+  try {
+    accessSync(dir, constants.W_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function fpathEntries(): string[] {
+  const raw = process.env.FPATH ?? process.env.fpath ?? ''
+  return raw.split(':').filter((entry) => entry !== '')
+}
+
+/**
+ * zsh only loads `_aimux` from a directory on `$fpath`. Prefer an existing,
+ * writable, user-owned fpath entry; otherwise fall back to the conventional
+ * site-functions dir and flag that the user must add it themselves.
+ */
+function zshTarget(): { onFpath: boolean; path: string } {
+  const fallback = join(dataHome(), 'zsh', 'site-functions')
+  const entries = fpathEntries()
+  const userOwned = entries.filter((entry) => entry.startsWith(home()) && isWritableDir(entry))
+  const preferred = userOwned[0]
+  if (preferred !== undefined) return { onFpath: true, path: join(preferred, '_aimux') }
+  return { onFpath: entries.includes(fallback), path: join(fallback, '_aimux') }
+}
+
+export function completionTarget(shell: SupportedShell): { onFpath: boolean; path: string } {
+  switch (shell) {
+    case 'bash':
+      // bash-completion v2 lazy-loads `<name>` from here on first TAB.
+      return {
+        onFpath: true,
+        path: join(dataHome(), 'bash-completion', 'completions', 'aimux'),
+      }
+    case 'fish':
+      return { onFpath: true, path: join(configHome(), 'fish', 'completions', 'aimux.fish') }
+    case 'zsh':
+      return zshTarget()
+  }
+}
+
+function markerPath(): string {
+  return join(getConfigProfilesRootDir(), 'completion-install.json')
+}
+
+function readMarker(): InstallMarker | null {
+  try {
+    const raw = readFileSync(markerPath(), 'utf8')
+    const parsed: unknown = JSON.parse(raw)
+    if (typeof parsed !== 'object' || parsed === null) return null
+    const marker = parsed as Partial<InstallMarker>
+    if (typeof marker.path !== 'string' || typeof marker.version !== 'string') return null
+    if (typeof marker.shell !== 'string' || !isSupportedShell(marker.shell)) return null
+    return {
+      installedAt: typeof marker.installedAt === 'string' ? marker.installedAt : '',
+      path: marker.path,
+      shell: marker.shell,
+      version: marker.version,
+    }
+  } catch {
+    return null
+  }
+}
+
+function writeMarker(result: InstallResult): void {
+  const marker: InstallMarker = {
+    installedAt: new Date().toISOString(),
+    path: result.path,
+    shell: result.shell,
+    version,
+  }
+  const path = markerPath()
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${JSON.stringify(marker, null, 2)}\n`)
+}
+
+/** Write the completion script for `shell`. Throws if the write fails. */
+export function installCompletionScript(shell: SupportedShell, command?: string): InstallResult {
+  const target = completionTarget(shell)
+  mkdirSync(dirname(target.path), { recursive: true })
+  writeFileSync(target.path, renderCompletionScript(shell, command))
+  const result: InstallResult = {
+    path: target.path,
+    pendingShellConfig: !target.onFpath,
+    shell,
+  }
+  writeMarker(result)
+  return result
+}
+
+/** The one-line fix a user needs when we couldn't guarantee auto-loading. */
+export function shellConfigHint(result: InstallResult): string {
+  if (!result.pendingShellConfig) return ''
+  if (result.shell === 'zsh') {
+    return `add to ~/.zshrc (before compinit): fpath=(${dirname(result.path)} $fpath)`
+  }
+  return `ensure your shell sources ${dirname(result.path)}`
+}
+
+export interface CompletionStatus {
+  detail: string
+  ok: boolean
+}
+
+/** What `aimux doctor` reports about shell completion. */
+export function completionStatus(): CompletionStatus {
+  const shell = detectShell()
+  if (shell === null) {
+    const name = process.env.SHELL ?? 'unknown'
+    return { detail: `no completion script for ${name}`, ok: true }
+  }
+  const target = completionTarget(shell)
+  if (!existsSync(target.path)) {
+    return { detail: `${shell}: not installed — run \`aimux completion install\``, ok: false }
+  }
+  if (!target.onFpath) {
+    const hint = shellConfigHint({ path: target.path, pendingShellConfig: true, shell })
+    return { detail: `${shell}: ${target.path} (${hint})`, ok: false }
+  }
+  return { detail: `${shell}: ${target.path}`, ok: true }
+}
+
+function autoInstallDisabled(): boolean {
+  const raw = process.env.AIMUX_NO_COMPLETION_INSTALL
+  return raw != null && raw !== '' && raw !== '0'
+}
+
+/**
+ * First-launch hook: install completion once per (version, shell), then never
+ * touch it again. Re-runs after an upgrade so a script generated from an older
+ * registry can't go stale. Best-effort — every failure is swallowed, because a
+ * missing completion script must never keep the TUI from starting.
+ */
+export function maybeAutoInstallCompletion(): InstallResult | null {
+  try {
+    if (autoInstallDisabled()) return null
+    const shell = detectShell()
+    if (shell === null) return null
+
+    const marker = readMarker()
+    if (
+      marker !== null &&
+      marker.shell === shell &&
+      marker.version === version &&
+      existsSync(marker.path)
+    ) {
+      return null
+    }
+
+    const result = installCompletionScript(shell)
+    logDebug('completion.autoInstalled', {
+      path: result.path,
+      pendingShellConfig: result.pendingShellConfig,
+      shell: result.shell,
+    })
+    return result
+  } catch (error) {
+    logDebug('completion.autoInstallFailed', {
+      message: error instanceof Error ? error.message : String(error),
+    })
+    return null
+  }
+}