@brimveyn/aimux 1.19.7 → 1.20.2

package/README.md

@@ -36,6 +36,12 @@ bun install -g @brimveyn/aimux
 
 Requires [Bun](https://bun.sh).
 
+Shell completion (bash, zsh, fish) installs itself the first time you launch
+the TUI — one file in your shell's completions directory, no dotfile edits.
+Run `aimux doctor` to see where it landed, or
+`aimux completion install --shell zsh` to place it yourself. Opt out with
+`AIMUX_NO_COMPLETION_INSTALL=1`. See [docs/reference/cli.md](docs/reference/cli.md#aimux-completion).
+
 ## Quick Start
 
 Create the default profile and install the typed config package into it:
@@ -157,6 +163,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 +174,12 @@ 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`. Pin the target
+with `--workspace` (or `AIMUX_WORKSPACE`) for anything long-running: the default
+follows whichever workspace the UI opened last.
+
 ## Runtime Model
 
 `aimux` is split into:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.19.7",
+  "version": "1.20.2",
   "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,127 @@
+---
+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 --workspace <target>
+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.
+
+**Pin the workspace and verify the repo before dispatching anything.** Without
+`--workspace` (or `AIMUX_WORKSPACE`) aimux targets whichever workspace the UI
+opened last, and that can change under you mid-run — including to a different
+project. Check `checks.workspace.repoRoot` in the doctor output against the
+repository you mean, then pass `--workspace <id|name>` on **every** call (all
+examples below do). Every worker response echoes `workspace.repoRoot`; read it on
+the first dispatch instead of assuming.
+
+## 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 \
+  --workspace <target> \
+  --name feat-auth \
+  --assistant claude \
+  --prompt-file /tmp/feat-auth.md \
+  --detach
+```
+
+5. Inspect the fleet with `aimux worker list --workspace <target>`.
+6. Await a detached worker with `aimux worker await feat-auth --workspace <target>`.
+7. If a worker asks a question, answer only when the plan already determines the
+   answer:
+
+```bash
+aimux worker prompt feat-auth --workspace <target> --replace --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 --workspace <target> --cleanup-worktree
+```
+
+## Dispatch failure modes
+
+Read these before the first dispatch; each one otherwise reads as a lost fleet.
+
+- **`status: "pending-submit"` (exit 11)** — the prompt is sitting unsubmitted in
+  the worker's composer. The worker is alive and healthy. Recover with
+  `aimux worker submit <name> --workspace <target>`; never re-dispatch, which
+  would double the fleet onto the same branches. Widen the confirmation window
+  with `--uptake-timeout <ms>` for slow-booting assistants.
+- **An empty `worker list`** — read the `workspace` field in the response. An
+  empty fleet in the wrong workspace is not a dead fleet. Add
+  `--all-workspaces` to answer "are they really gone?" in one call;
+  `git worktree list` in the target repo is the on-disk cross-check.
+- **Composer contamination** — a human typing in a worker's tab leaves text that
+  `worker prompt` would append to, merging both into one incoherent instruction.
+  Use `--replace` (clears with `<C-u>`) for every correction, and
+  `aimux tab snapshot <tabId>` when a worker's behaviour doesn't match the
+  prompt you believe you sent.
+- **Fresh worktrees are not provisioned** — a new worktree has no installed
+  dependencies and no generated files. Every dispatch prompt must tell the worker
+  to bootstrap before running any gate (see `references/prompts.md`), or it will
+  report environment failures as its own.
+
+## 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.
+- Pass `--workspace` on every call, and confirm the `repoRoot` the first response
+  reports is the repository you intend to change.
+
+## 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,68 @@
+# 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>
+
+## Environment
+
+This is a fresh worktree: it has no installed dependencies and no generated
+files. Run <the repo's install + codegen commands> before any verification gate,
+and report a bootstrap failure as a bootstrap failure — never as a failing gate.
+
+## 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.
+
+Keep the **Environment** block. A fresh `git worktree` shares history, not build
+state: no `node_modules`, no generated clients or route files. Without it workers
+run the gates in a half-provisioned tree, fail for environment reasons, and report
+those failures as if they were their own.
+
+## 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/client/workspace-resolver.ts

@@ -1,17 +1,55 @@
-import type { SessionRecord } from '../../state/types'
+import type { SessionRecord, WorktreeRecord } from '../../state/types'
 
 import { findMostRecentSession, loadSessionCatalog } from '../../state/session-catalog'
 
 /**
- * Resolve `--workspace W` to a session record from the catalog. Falls back to
- * the most recently opened session when the flag is absent. Throws when the
- * catalog is empty (no session has ever been created) or when the explicit
- * name/id doesn't match.
+ * Where a command's target workspace came from. An orchestrator needs this to
+ * tell "I asked for pragma-once" from "aimux guessed, and the UI had moved on":
+ * `active` is the only origin that can silently follow the UI to another repo.
+ */
+export type WorkspaceOrigin = 'flag' | 'env' | 'active'
+
+export interface ResolvedWorkspace {
+  origin: WorkspaceOrigin
+  record: SessionRecord
+}
+
+/** Env pin for headless orchestrators — `--workspace` still wins over it. */
+export const WORKSPACE_ENV_VAR = 'AIMUX_WORKSPACE'
+
+/** The workspace's primary (root) worktree, i.e. the repository it is about. */
+export function findPrimaryWorktree(session: SessionRecord): WorktreeRecord | undefined {
+  return session.worktrees?.find((worktree) => worktree.source === 'primary')
+}
+
+/**
+ * The repo every fresh worktree for this workspace is cut from. Surfaced in
+ * every worker envelope so an agent can see *which project* it just acted on
+ * instead of inferring it from a worktree path hash.
+ */
+export function workspaceRepoRoot(session: SessionRecord): string | null {
+  return findPrimaryWorktree(session)?.repoRoot ?? session.projectPath ?? null
+}
+
+/** Stable workspace identity block embedded in command output. */
+export function workspaceIdentity(session: SessionRecord): {
+  id: string
+  name: string
+  repoRoot: string | null
+} {
+  return { id: session.id, name: session.name, repoRoot: workspaceRepoRoot(session) }
+}
+
+/**
+ * Resolve `--workspace W` to a session record from the catalog, reporting where
+ * the choice came from. Precedence: the explicit flag, then `AIMUX_WORKSPACE`,
+ * then the most recently opened session. Throws when the catalog is empty (no
+ * session has ever been created) or when the explicit name/id doesn't match.
  *
  * Matching: exact id wins; otherwise exact name (case-sensitive); otherwise
  * unique case-insensitive name match.
  */
-export function resolveWorkspace(name: string | undefined): SessionRecord {
+export function resolveWorkspaceWithOrigin(name: string | undefined): ResolvedWorkspace {
   const sessions = loadSessionCatalog()
   if (sessions.length === 0) {
     throw new Error(
@@ -19,14 +57,29 @@ export function resolveWorkspace(name: string | undefined): SessionRecord {
     )
   }
 
-  if (name === undefined || name === '') {
+  const flag = name !== undefined && name !== '' ? name : undefined
+  const env = process.env[WORKSPACE_ENV_VAR]
+  const fromEnv = env != null && env !== '' ? env : undefined
+  const selector = flag ?? fromEnv
+  if (selector === undefined) {
     const active = findMostRecentSession(sessions)
     if (!active) {
       throw new Error('no active workspace and the catalog is empty')
     }
-    return active
+    return { origin: 'active', record: active }
+  }
+
+  return {
+    origin: flag !== undefined ? 'flag' : 'env',
+    record: matchWorkspace(sessions, selector),
   }
+}
+
+export function resolveWorkspace(name: string | undefined): SessionRecord {
+  return resolveWorkspaceWithOrigin(name).record
+}
 
+function matchWorkspace(sessions: SessionRecord[], name: string): SessionRecord {
   const byId = sessions.find((session) => session.id === name)
   if (byId) return byId
 

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

@@ -27,7 +27,7 @@ import { awaitTurn, DEFAULT_TIMEOUT_MS, type TurnOutcome, turnOutcomeExitCode }
 const QUESTION_TAIL_LINES = 25
 
 export const tabAwait: CliCommand = {
-  args: [{ name: 'tabId', required: true }],
+  args: [{ complete: { kind: 'dynamic', source: 'tab' }, name: 'tabId', required: true }],
   flags: [
     ...SHARED_FLAGS,
     {

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

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