@brimveyn/aimux 1.19.7 → 1.20.1

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

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

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

@@ -0,0 +1,129 @@
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import type { CliCommand } from '../../registry'
+
+import { loadConfig } from '../../../config'
+import { MANAGER_CAPABILITY_WORKER_METADATA } from '../../../ipc/manager-protocol'
+import {
+  IPC_CAPABILITY_LIST_TABS,
+  IPC_CAPABILITY_QUESTION_EVENTS,
+  IPC_CAPABILITY_THIN_ATTACH,
+  IPC_CAPABILITY_TURN_LIFECYCLE,
+  IPC_CAPABILITY_WORKER_METADATA,
+  IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS,
+} from '../../../ipc/protocol'
+import {
+  getAllAssistantOptions,
+  isCommandAvailable,
+  parseCommand,
+} from '../../../pty/command-registry'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, EXIT_RUNTIME, writeJson } from '../../output'
+import { WORKER_SCHEMA_VERSION } from './shared'
+
+const REQUIRED_DAEMON_CAPABILITIES = [
+  IPC_CAPABILITY_LIST_TABS,
+  IPC_CAPABILITY_QUESTION_EVENTS,
+  IPC_CAPABILITY_THIN_ATTACH,
+  IPC_CAPABILITY_TURN_LIFECYCLE,
+  IPC_CAPABILITY_WORKER_METADATA,
+  IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS,
+] as const
+
+export const workerDoctor: CliCommand = {
+  args: [],
+  flags: SHARED_FLAGS,
+  group: 'worker',
+  run: async (ctx) => {
+    const daemon = await ctx.getDaemon()
+    const workspace = ctx.getWorkspace()
+    const { version } = await import('../../../../package.json')
+    const { customCommands } = loadConfig()
+    const assistants = getAllAssistantOptions(customCommands).map((assistant) => ({
+      available: isCommandAvailable(
+        parseCommand(customCommands[assistant.id] ?? assistant.command).executable
+      ),
+      id: assistant.id,
+      supportsEffort: assistant.model?.buildEffortArgs !== undefined,
+      supportsModel: assistant.model?.buildModelArgs !== undefined,
+    }))
+    const daemonCapabilities = daemon.getCapabilities()
+    const managerCapabilities = daemon.getManagerCapabilities()
+    const missingDaemonCapabilities = REQUIRED_DAEMON_CAPABILITIES.filter(
+      (capability) => !daemonCapabilities.includes(capability)
+    )
+    const missingManagerCapabilities = [MANAGER_CAPABILITY_WORKER_METADATA].filter(
+      (capability) => !managerCapabilities.includes(capability)
+    )
+    const primaryWorktree = workspace.worktrees?.find((worktree) => worktree.source === 'primary')
+    const availableAssistants = assistants.filter((assistant) => assistant.available)
+    const skillPath = fileURLToPath(
+      new URL('../../../../skills/aimux-orchestrator/', import.meta.url)
+    )
+    const issues: string[] = []
+    if (missingDaemonCapabilities.length > 0) {
+      issues.push(
+        `restart or update aimux; daemon is missing: ${missingDaemonCapabilities.join(', ')}`
+      )
+    }
+    if (missingManagerCapabilities.length > 0) {
+      issues.push(
+        `restart the terminal manager; it is missing: ${missingManagerCapabilities.join(', ')}`
+      )
+    }
+    if (primaryWorktree === undefined) {
+      issues.push('workspace has no primary worktree; default isolated worker runs are unavailable')
+    }
+    if (availableAssistants.length === 0) {
+      issues.push('no configured assistant executable is available on PATH')
+    }
+    if (!existsSync(skillPath)) {
+      issues.push(`packaged orchestrator skill is missing: ${skillPath}`)
+    }
+    const ready = issues.length === 0
+    writeJson({
+      assistants,
+      checks: {
+        assistants: {
+          available: availableAssistants.map((assistant) => assistant.id),
+          ok: availableAssistants.length > 0,
+        },
+        daemonCapabilities: {
+          missing: missingDaemonCapabilities,
+          ok: missingDaemonCapabilities.length === 0,
+        },
+        managerCapabilities: {
+          missing: missingManagerCapabilities,
+          ok: missingManagerCapabilities.length === 0,
+        },
+        skill: { ok: existsSync(skillPath), path: skillPath },
+        workspace: {
+          hasPrimaryWorktree: primaryWorktree !== undefined,
+          ok: primaryWorktree !== undefined,
+        },
+      },
+      cliVersion: version,
+      daemon: {
+        appVersion: daemon.getAppVersion(),
+        capabilities: daemonCapabilities,
+        managerCapabilities,
+        managerProtocolVersion: daemon.getManagerSelectedVersion(),
+        processVersion: daemon.getProcessVersion(),
+        protocolVersion: daemon.getSelectedVersion(),
+      },
+      issues,
+      ready,
+      schemaVersion: WORKER_SCHEMA_VERSION,
+      skillPath,
+      workspace: {
+        id: workspace.id,
+        name: workspace.name,
+        projectPath: workspace.projectPath ?? null,
+      },
+    })
+    return ready ? EXIT_OK : EXIT_RUNTIME
+  },
+  summary: 'Check worker prerequisites, versions, assistants, and workspace',
+  verb: 'doctor',
+}

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

@@ -0,0 +1,25 @@
+import type { CliCommand } from '../../registry'
+
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+import { listNamedWorkerTabs, resolveWorkerTab, WORKER_SCHEMA_VERSION, workerView } from './shared'
+
+export const workerList: CliCommand = {
+  args: [{ name: 'worker' }],
+  flags: SHARED_FLAGS,
+  group: 'worker',
+  run: async (ctx) => {
+    const selector = ctx.args.positionals[0]
+    const tabs =
+      selector === undefined
+        ? await listNamedWorkerTabs(ctx)
+        : [await resolveWorkerTab(ctx, selector)]
+    writeJson({
+      schemaVersion: WORKER_SCHEMA_VERSION,
+      workers: tabs.map((tab) => workerView(ctx, tab)),
+    })
+    return EXIT_OK
+  },
+  summary: 'List named workers with liveness and worktree context',
+  verb: 'list',
+}

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

@@ -0,0 +1,49 @@
+import type { CliCommand } from '../../registry'
+
+import { SHARED_FLAGS } from '../../flags'
+import { writeJson } from '../../output'
+import { DEFAULT_TIMEOUT_MS } from '../tab/await-turn'
+import { resolvePromptText } from '../tab/prompt-io'
+import {
+  dispatchWorkerPrompt,
+  resolveWorkerTab,
+  workerEnvelope,
+  workerOutcomeExitCode,
+  workerView,
+} from './shared'
+
+export const workerPrompt: CliCommand = {
+  args: [{ name: 'worker', required: true }, { name: 'text' }],
+  flags: [
+    ...SHARED_FLAGS,
+    { description: 'read the prompt from this file', kind: 'string', name: 'prompt-file' },
+    { description: 'read the prompt from stdin', kind: 'boolean', name: 'stdin' },
+    {
+      description: 'return after prompt uptake instead of turn completion',
+      kind: 'boolean',
+      name: 'detach',
+    },
+    { description: 'overall turn cap in milliseconds', kind: 'number', name: 'timeout' },
+  ],
+  group: 'worker',
+  run: async (ctx) => {
+    const selector = ctx.args.positionals[0] ?? ''
+    const tab = await resolveWorkerTab(ctx, selector)
+    const promptFile =
+      typeof ctx.args.flags['prompt-file'] === 'string' ? ctx.args.flags['prompt-file'] : undefined
+    const text = await resolvePromptText(
+      promptFile,
+      ctx.args.flags.stdin === true,
+      ctx.args.positionals[1]
+    )
+    const outcome = await dispatchWorkerPrompt(ctx, tab.id, text, {
+      detach: ctx.args.flags.detach === true,
+      timeoutMs:
+        typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_TIMEOUT_MS,
+    })
+    writeJson(workerEnvelope(workerView(ctx, tab), outcome))
+    return workerOutcomeExitCode(outcome)
+  },
+  summary: 'Prompt an existing named worker and await its outcome',
+  verb: 'prompt',
+}

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

@@ -0,0 +1,97 @@
+import type { CliCommand } from '../../registry'
+
+import { CliUsageError, SHARED_FLAGS } from '../../flags'
+import { writeJson } from '../../output'
+import { DEFAULT_TIMEOUT_MS } from '../tab/await-turn'
+import { createCliTab } from '../tab/create'
+import { resolvePromptText } from '../tab/prompt-io'
+import {
+  dispatchWorkerPrompt,
+  validateWorkerName,
+  workerEnvelope,
+  workerOutcomeExitCode,
+  workerView,
+} from './shared'
+
+export const workerRun: CliCommand = {
+  args: [{ name: 'text' }],
+  flags: [
+    ...SHARED_FLAGS,
+    { description: 'unique workspace-scoped worker name', kind: 'string', name: 'name' },
+    {
+      description: 'assistant id (claude, codex, opencode, ...)',
+      kind: 'string',
+      name: 'assistant',
+    },
+    { description: 'model passed through to the assistant', kind: 'string', name: 'model' },
+    {
+      description: 'reasoning effort passed through to the assistant',
+      kind: 'string',
+      name: 'effort',
+    },
+    { description: 'read the prompt from this file', kind: 'string', name: 'prompt-file' },
+    { description: 'read the prompt from stdin', kind: 'boolean', name: 'stdin' },
+    {
+      description: 'return after prompt uptake instead of turn completion',
+      kind: 'boolean',
+      name: 'detach',
+    },
+    { description: 'overall turn cap in milliseconds', kind: 'number', name: 'timeout' },
+    { description: 'co-locate in an existing worktree id', kind: 'string', name: 'worktree' },
+    {
+      description: 'run in the workspace active worktree instead of creating one',
+      kind: 'boolean',
+      name: 'no-worktree',
+    },
+    { description: 'base ref for the fresh worktree (default HEAD)', kind: 'string', name: 'base' },
+    {
+      description: 'branch for the fresh worktree (default aimux/<name>)',
+      kind: 'string',
+      name: 'branch',
+    },
+  ],
+  group: 'worker',
+  run: async (ctx) => {
+    const name = typeof ctx.args.flags.name === 'string' ? ctx.args.flags.name : ''
+    const assistant = typeof ctx.args.flags.assistant === 'string' ? ctx.args.flags.assistant : ''
+    validateWorkerName(name)
+    if (assistant === '') throw new CliUsageError('--assistant is required')
+    const worktree =
+      typeof ctx.args.flags.worktree === 'string' ? ctx.args.flags.worktree : undefined
+    const noWorktree = ctx.args.flags['no-worktree'] === true
+    if (worktree !== undefined && noWorktree) {
+      throw new CliUsageError('--worktree and --no-worktree are mutually exclusive')
+    }
+    const promptFile =
+      typeof ctx.args.flags['prompt-file'] === 'string' ? ctx.args.flags['prompt-file'] : undefined
+    const text = await resolvePromptText(
+      promptFile,
+      ctx.args.flags.stdin === true,
+      ctx.args.positionals[0]
+    )
+    const result = await createCliTab(ctx, {
+      assistantId: assistant,
+      base: typeof ctx.args.flags.base === 'string' ? ctx.args.flags.base : undefined,
+      branch: typeof ctx.args.flags.branch === 'string' ? ctx.args.flags.branch : undefined,
+      effort: typeof ctx.args.flags.effort === 'string' ? ctx.args.flags.effort : undefined,
+      model: typeof ctx.args.flags.model === 'string' ? ctx.args.flags.model : undefined,
+      newWorktree: noWorktree || worktree !== undefined ? undefined : name,
+      title: name,
+      workerName: name,
+      worktreeId: worktree,
+    })
+    const tabs = await (await ctx.getDaemon()).listTabs(ctx.getWorkspace().id)
+    const tab = tabs.tabs.find((entry) => entry.id === result.tabId)
+    if (!tab) throw new Error(`created worker disappeared: ${result.tabId}`)
+    const worker = workerView(ctx, tab)
+    const outcome = await dispatchWorkerPrompt(ctx, result.tabId, text, {
+      detach: ctx.args.flags.detach === true,
+      timeoutMs:
+        typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_TIMEOUT_MS,
+    })
+    writeJson(workerEnvelope(worker, outcome))
+    return workerOutcomeExitCode(outcome)
+  },
+  summary: 'Create a named worker, dispatch a prompt, and await its outcome',
+  verb: 'run',
+}

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

@@ -0,0 +1,255 @@
+import type { WorktreeRecord } from '../../../state/types'
+import type { CliContext } from '../../context'
+
+import {
+  IPC_CAPABILITY_LIST_TABS,
+  IPC_CAPABILITY_QUESTION_EVENTS,
+  IPC_CAPABILITY_THIN_ATTACH,
+  IPC_CAPABILITY_TURN_LIFECYCLE,
+  IPC_CAPABILITY_WORKER_METADATA,
+  type TabSessionSummary,
+} from '../../../ipc/protocol'
+import { CliUsageError } from '../../flags'
+import { EXIT_OK, EXIT_QUESTION, EXIT_RUNTIME, EXIT_TIMEOUT } from '../../output'
+import { snapshotTailLines } from '../../snapshot-render'
+import { awaitTurn, type TurnOutcome } from '../tab/await-turn'
+import { buildPromptPayload, writePromptPayload } from '../tab/prompt-io'
+
+export const WORKER_SCHEMA_VERSION = 1
+export const WORKER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
+const QUESTION_TAIL_LINES = 25
+const DETACH_UPTAKE_TIMEOUT_MS = 15_000
+
+export interface WorkerView {
+  activity?: TabSessionSummary['activity']
+  assistant: string
+  branch: string | null
+  command: string
+  lastLine?: string
+  name: string
+  path: string | null
+  status: TabSessionSummary['status']
+  tabId: string
+  title: string
+  worktreeId: string | null
+}
+
+export interface WorkerOutcome {
+  durationMs: number
+  error?: string
+  kind?: string
+  options?: string[]
+  question?: string
+  status: 'completed' | 'dispatched' | 'question' | 'timeout' | 'error'
+  uptake?: { confirmed: boolean; ms?: number }
+}
+
+export function validateWorkerName(name: string): void {
+  if (!WORKER_NAME_PATTERN.test(name)) {
+    throw new CliUsageError(
+      'worker name must be 1-64 characters: letters, numbers, dot, underscore, or hyphen'
+    )
+  }
+}
+
+function worktreeFor(ctx: CliContext, worktreeId: string | undefined): WorktreeRecord | undefined {
+  if (worktreeId === undefined) return undefined
+  return ctx.getWorkspace().worktrees?.find((worktree) => worktree.id === worktreeId)
+}
+
+export function workerView(ctx: CliContext, tab: TabSessionSummary): WorkerView {
+  if (tab.workerName === undefined) {
+    throw new Error(`tab is not a named worker: ${tab.id}`)
+  }
+  const worktree = worktreeFor(ctx, tab.worktreeId)
+  return {
+    activity: tab.activity,
+    assistant: tab.assistant,
+    branch: worktree?.branch ?? null,
+    command: tab.command,
+    lastLine: tab.lastLine,
+    name: tab.workerName,
+    path: worktree?.path ?? null,
+    status: tab.status,
+    tabId: tab.id,
+    title: tab.title,
+    worktreeId: tab.worktreeId ?? null,
+  }
+}
+
+export async function listNamedWorkerTabs(ctx: CliContext): Promise<TabSessionSummary[]> {
+  const daemon = await ctx.getDaemon()
+  if (
+    !daemon.hasCapability(IPC_CAPABILITY_LIST_TABS) ||
+    !daemon.hasCapability(IPC_CAPABILITY_WORKER_METADATA)
+  ) {
+    throw new Error('daemon predates worker commands — restart aimux')
+  }
+  return (await daemon.listTabs(ctx.getWorkspace().id)).tabs.filter(
+    (tab) => tab.workerName !== undefined
+  )
+}
+
+export async function resolveWorkerTab(
+  ctx: CliContext,
+  selector: string
+): Promise<TabSessionSummary> {
+  const workers = await listNamedWorkerTabs(ctx)
+  const byId = workers.find((tab) => tab.id === selector)
+  if (byId) return byId
+  const matches = workers.filter((tab) => tab.workerName === selector)
+  if (matches.length === 1 && matches[0]) return matches[0]
+  if (matches.length > 1) {
+    throw new Error(
+      `worker selector is ambiguous: ${selector} (${matches.map((tab) => tab.id).join(', ')})`
+    )
+  }
+  throw new Error(`worker not found: ${selector}`)
+}
+
+export function normalizeTurnOutcome(outcome: TurnOutcome): WorkerOutcome {
+  switch (outcome.outcome) {
+    case 'completed':
+      return { durationMs: outcome.durationMs, status: 'completed' }
+    case 'question':
+      return {
+        durationMs: outcome.durationMs,
+        kind: outcome.kind,
+        options: outcome.options,
+        question: outcome.question,
+        status: 'question',
+      }
+    case 'timeout':
+      return { durationMs: outcome.durationMs, status: 'timeout' }
+    case 'error':
+      return { durationMs: outcome.durationMs, error: outcome.error, status: 'error' }
+  }
+}
+
+export function workerOutcomeExitCode(outcome: WorkerOutcome): number {
+  switch (outcome.status) {
+    case 'completed':
+    case 'dispatched':
+      return EXIT_OK
+    case 'question':
+      return EXIT_QUESTION
+    case 'timeout':
+      return EXIT_TIMEOUT
+    case 'error':
+      return EXIT_RUNTIME
+  }
+}
+
+async function requireTurnCapabilities(ctx: CliContext): Promise<{
+  daemon: Awaited<ReturnType<CliContext['getDaemon']>>
+}> {
+  const daemon = await ctx.getDaemon()
+  if (
+    !daemon.hasCapability(IPC_CAPABILITY_THIN_ATTACH) ||
+    !daemon.hasCapability(IPC_CAPABILITY_TURN_LIFECYCLE) ||
+    !daemon.hasCapability(IPC_CAPABILITY_QUESTION_EVENTS)
+  ) {
+    throw new Error('daemon predates worker turn lifecycle — restart aimux')
+  }
+  return { daemon }
+}
+
+export async function dispatchWorkerPrompt(
+  ctx: CliContext,
+  tabId: string,
+  text: string,
+  options: { detach: boolean; timeoutMs: number }
+): Promise<WorkerOutcome> {
+  const { daemon } = await requireTurnCapabilities(ctx)
+  const workspace = ctx.getWorkspace()
+  const attach = await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+  if (!attach.tabs.some((tab) => tab.id === tabId)) throw new Error(`tab not found: ${tabId}`)
+  const payload = buildPromptPayload(text, false)
+
+  if (!options.detach) {
+    const outcome = await awaitTurn({
+      assumeWorking: false,
+      daemon,
+      onArmed: async () => {
+        await writePromptPayload(daemon, tabId, payload, true)
+      },
+      tabId,
+      timeoutMs: options.timeoutMs,
+    })
+    return normalizeTurnOutcome(outcome)
+  }
+
+  const startedAt = Date.now()
+  const uptake = new Promise<{ confirmed: true; ms: number } | { confirmed: false }>((resolve) => {
+    const off = daemon.on('tabStatus', (event) => {
+      if (event.tabId !== tabId || event.status !== 'working') return
+      off()
+      clearTimeout(timer)
+      resolve({ confirmed: true, ms: Date.now() - startedAt })
+    })
+    const timer = setTimeout(
+      () => {
+        off()
+        resolve({ confirmed: false })
+      },
+      Math.min(options.timeoutMs, DETACH_UPTAKE_TIMEOUT_MS)
+    )
+  })
+  await writePromptPayload(daemon, tabId, payload, true)
+  const result = await uptake
+  if (!result.confirmed) {
+    return {
+      durationMs: Date.now() - startedAt,
+      error: 'prompt was written but worker uptake was not confirmed',
+      status: 'error',
+      uptake: result,
+    }
+  }
+  return {
+    durationMs: Date.now() - startedAt,
+    status: 'dispatched',
+    uptake: result,
+  }
+}
+
+export async function awaitExistingWorker(
+  ctx: CliContext,
+  tabId: string,
+  timeoutMs: number
+): Promise<WorkerOutcome> {
+  const { daemon } = await requireTurnCapabilities(ctx)
+  const attach = await daemon.attach({
+    cols: 0,
+    rows: 0,
+    sessionId: ctx.getWorkspace().id,
+    thin: true,
+  })
+  const tab = attach.tabs.find((entry) => entry.id === tabId)
+  if (!tab) throw new Error(`tab not found: ${tabId}`)
+  if (tab.activity === 'waiting-input') {
+    const question =
+      tab.viewport && tab.viewport.lines.length > 0
+        ? snapshotTailLines(tab.viewport, QUESTION_TAIL_LINES, { trim: true }).join('\n')
+        : ''
+    return { durationMs: 0, kind: 'question', question, status: 'question' }
+  }
+  return normalizeTurnOutcome(
+    await awaitTurn({
+      assumeWorking: tab.activity === 'working',
+      daemon,
+      tabId,
+      timeoutMs,
+    })
+  )
+}
+
+export function workerEnvelope(
+  worker: WorkerView,
+  outcome?: WorkerOutcome
+): Record<string, unknown> {
+  return {
+    schemaVersion: WORKER_SCHEMA_VERSION,
+    worker,
+    ...(outcome === undefined ? {} : { outcome }),
+  }
+}

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

@@ -0,0 +1,84 @@
+import type { CliCommand } from '../../registry'
+
+import { isGitWorktreeDirty, removeGitWorktree } from '../../../git/worktree'
+import { IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS } from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+import { resolveWorkerTab, WORKER_SCHEMA_VERSION, workerView } from './shared'
+
+export const workerStop: CliCommand = {
+  args: [{ name: 'worker', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    {
+      description: 'remove its aimux-created worktree after closing the tab',
+      kind: 'boolean',
+      name: 'cleanup-worktree',
+    },
+    { description: 'force removal of a dirty worktree', kind: 'boolean', name: 'force' },
+  ],
+  group: 'worker',
+  run: async (ctx) => {
+    const tab = await resolveWorkerTab(ctx, ctx.args.positionals[0] ?? '')
+    const worker = workerView(ctx, tab)
+    const daemon = await ctx.getDaemon()
+    const workspace = ctx.getWorkspace()
+    const cleanup = ctx.args.flags['cleanup-worktree'] === true
+    const record =
+      tab.worktreeId === undefined
+        ? undefined
+        : workspace.worktrees?.find((worktree) => worktree.id === tab.worktreeId)
+
+    if (cleanup) {
+      if (record === undefined) throw new Error('worker has no registered worktree to clean up')
+      if (record.source !== 'aimux-temp' || !record.createdByAimux) {
+        throw new Error('refusing to clean up a primary or externally managed worktree')
+      }
+      const siblings = (await daemon.listTabs(workspace.id)).tabs.filter(
+        (entry) => entry.id !== tab.id && entry.worktreeId === record.id
+      )
+      if (siblings.length > 0) {
+        throw new Error(
+          `refusing to clean up shared worktree; live tabs: ${siblings.map((entry) => entry.id).join(', ')}`
+        )
+      }
+      if (!daemon.hasCapability(IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS)) {
+        throw new Error('daemon predates safe worktree cleanup — restart aimux')
+      }
+      if (ctx.args.flags.force !== true && (await isGitWorktreeDirty(record.path))) {
+        throw new Error('refusing to clean up a dirty worktree without --force')
+      }
+    }
+
+    await daemon.expectOk('closeTab', { tabId: tab.id })
+    let worktreeRemoved = false
+    if (cleanup && record !== undefined) {
+      await removeGitWorktree({
+        force: ctx.args.flags.force === true,
+        repoPath: record.repoRoot,
+        targetPath: record.path,
+      })
+      try {
+        await daemon.expectOk('removeWorktreeRecord', {
+          sessionId: workspace.id,
+          worktreeId: record.id,
+        })
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        throw new Error(
+          `worker stopped and git worktree removed, but catalog reconciliation failed: ${message}`
+        )
+      }
+      worktreeRemoved = true
+    }
+    writeJson({
+      closed: true,
+      schemaVersion: WORKER_SCHEMA_VERSION,
+      worker,
+      worktreeRemoved,
+    })
+    return EXIT_OK
+  },
+  summary: 'Stop a named worker and optionally clean up its worktree',
+  verb: 'stop',
+}