@brimveyn/aimux 1.20.1 → 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:
@@ -170,7 +176,9 @@ 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`.
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.20.1",
+  "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",

package/skills/aimux-orchestrator/SKILL.md

@@ -12,7 +12,7 @@ Own the plan and quality gate. Let aimux own worker transport and lifecycle.
 Run once:
 
 ```bash
-aimux worker doctor
+aimux worker doctor --workspace <target>
 aimux worker --help
 ```
 
@@ -20,6 +20,14 @@ 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.
@@ -29,19 +37,20 @@ to screen scraping or the legacy shell wrappers.
 
 ```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`.
-6. Await a detached worker with `aimux worker await feat-auth`.
+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 --prompt-file /tmp/answer.md
+aimux worker prompt feat-auth --workspace <target> --replace --prompt-file /tmp/answer.md
 ```
 
 Escalate design choices, irreversible operations, deployments, pushes,
@@ -54,9 +63,32 @@ migrations, spending, and external communication to the human.
 10. After integration, close and clean up:
 
 ```bash
-aimux worker stop feat-auth --cleanup-worktree
+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
@@ -78,6 +110,8 @@ may overlap or scope is uncertain.
 - 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
 

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

@@ -23,6 +23,12 @@
 
 - <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.
@@ -32,6 +38,11 @@ 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

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) => {

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

@@ -13,6 +13,7 @@ import {
   IPC_CAPABILITY_WORKER_METADATA,
 } from '../../../ipc/protocol'
 import { createPrefixedId } from '../../../platform/id'
+import { pruneEmptyWorktreeParent } from '../../../platform/worktree-paths'
 import {
   type AssistantOption,
   buildAssistantModelArgs,
@@ -98,6 +99,7 @@ async function rollbackCreatedWorktree(
       repoPath: record.repoRoot,
       targetPath: record.path,
     })
+    await pruneEmptyWorktreeParent(record.path)
     await daemon.expectOk('removeWorktreeRecord', {
       sessionId: workspace.id,
       worktreeId: record.id,
@@ -272,39 +274,61 @@ export const tabCreate: CliCommand = {
   flags: [
     ...SHARED_FLAGS,
     {
+      complete: { kind: 'dynamic', source: 'assistant' },
       description: 'assistant id (claude, codex, opencode, grok, kimi, terminal, ...)',
       kind: 'string',
       name: 'assistant',
     },
-    { description: 'tab title (defaults to assistant label)', kind: 'string', name: 'title' },
-    { description: 'cwd for the spawned PTY', kind: 'string', name: 'cwd' },
     {
+      complete: { kind: 'none' },
+      description: 'tab title (defaults to assistant label)',
+      kind: 'string',
+      name: 'title',
+    },
+    {
+      complete: { kind: 'file' },
+      description: 'cwd for the spawned PTY',
+      kind: 'string',
+      name: 'cwd',
+    },
+    {
+      complete: { kind: 'none' },
       description: 'explicit command (overrides the assistant default)',
       kind: 'string',
       name: 'command',
     },
     {
+      complete: { kind: 'none' },
       description: 'model for the worker (maps to the assistant’s model flag)',
       kind: 'string',
       name: 'model',
     },
     {
+      complete: { kind: 'none' },
       description: 'reasoning-effort level (maps to the assistant’s effort flag)',
       kind: 'string',
       name: 'effort',
     },
     {
+      complete: { kind: 'dynamic', source: 'worktree' },
       description: 'worktree id the tab belongs to (defaults to the workspace’s active worktree)',
       kind: 'string',
       name: 'worktree',
     },
     {
+      complete: { kind: 'none' },
       description: 'create a fresh worktree for this tab (optionally named: --new-worktree=<name>)',
       kind: 'optional-string',
       name: 'new-worktree',
     },
-    { description: 'base ref for --new-worktree (default HEAD)', kind: 'string', name: 'base' },
     {
+      complete: { kind: 'dynamic', source: 'git-ref' },
+      description: 'base ref for --new-worktree (default HEAD)',
+      kind: 'string',
+      name: 'base',
+    },
+    {
+      complete: { kind: 'none' },
       description: 'branch for --new-worktree (default aimux/<name>)',
       kind: 'string',
       name: 'branch',

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

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

package/src/cli/commands/tab/prompt-io.ts

@@ -92,7 +92,12 @@ export async function writePromptPayload(
   payload: PromptPayload,
   appendEnter: boolean
 ): Promise<number> {
-  await daemon.expectOk('write', { data: payload.data, tabId })
+  // Skip a zero-length write: "submit only" (empty payload + --enter) is a
+  // legitimate operation, but a 0-byte write reaches the pty as an empty
+  // ArrayBufferView and surfaces a raw Bun ERR_INVALID_ARG_TYPE to the user.
+  if (payload.data !== '') {
+    await daemon.expectOk('write', { data: payload.data, tabId })
+  }
   let bytesWritten = Buffer.byteLength(payload.data, 'utf8')
   if (appendEnter) {
     // A bracketed paste swallows a same-burst `\r`, so settle first, then

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

@@ -20,10 +20,18 @@ import { awaitTurn, DEFAULT_TIMEOUT_MS, turnOutcomeExitCode } from './await-turn
 import { buildPromptPayload, resolvePromptText, writePromptPayload } from './prompt-io'
 
 export const tabRun: CliCommand = {
-  args: [{ name: 'tabId', required: true }, { name: 'text' }],
+  args: [
+    { complete: { kind: 'dynamic', source: 'tab' }, name: 'tabId', required: true },
+    { complete: { kind: 'none' }, name: 'text' },
+  ],
   flags: [
     ...SHARED_FLAGS,
-    { description: 'read the prompt from this file', kind: 'string', name: 'prompt-file' },
+    {
+      complete: { kind: 'file' },
+      description: 'read the prompt from this file',
+      kind: 'string',
+      name: 'prompt-file',
+    },
     { description: 'read the prompt from stdin', kind: 'boolean', name: 'stdin' },
     {
       description: 'overall turn cap in milliseconds (default 900000 = 15 min)',

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

@@ -9,7 +9,10 @@ import { buildPromptPayload, writePromptPayload } from './prompt-io'
 const DEFAULT_AWAIT_TIMEOUT_MS = 15_000
 
 export const tabSend: CliCommand = {
-  args: [{ name: 'tabId', required: true }, { name: 'text' }],
+  args: [
+    { complete: { kind: 'dynamic', source: 'tab' }, name: 'tabId', required: true },
+    { complete: { kind: 'none' }, name: 'text' },
+  ],
   flags: [
     ...SHARED_FLAGS,
     { description: 'append \\r so the receiving CLI submits', kind: 'boolean', name: 'enter' },
@@ -24,6 +27,7 @@ export const tabSend: CliCommand = {
       name: 'stdin',
     },
     {
+      complete: { kind: 'file' },
       description: 'read the payload from this file instead of <text>',
       kind: 'string',
       name: 'prompt-file',
@@ -59,12 +63,13 @@ export const tabSend: CliCommand = {
         ? ctx.args.flags['await-timeout']
         : DEFAULT_AWAIT_TIMEOUT_MS
 
-    // Uptake only means something once we actually submit the prompt: the
-    // working transition is the receiving CLI accepting the Enter. Without
-    // --enter there is nothing to confirm, so fail loudly rather than block
-    // forever on a transition that can't come.
-    if (awaitSubmit && !appendEnter) {
-      throw new Error('--await-submit requires --enter')
+    // Uptake only means something once something submits: either the appended
+    // `\r` (--enter) or a chord that carries its own submit (--keys "<CR>",
+    // which is the recovery path for a prompt already sitting in a composer).
+    // Without one of those there is nothing to confirm, so fail loudly rather
+    // than block forever on a transition that can't come.
+    if (awaitSubmit && !appendEnter && !asKeys) {
+      throw new Error('--await-submit requires --enter or --keys (the chord carries the submit)')
     }
 
     // At most one payload source. Unlike `tab run`, zero sources is valid here

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

@@ -9,11 +9,12 @@ import { snapshotTailLines, snapshotToLines } from '../../snapshot-render'
 const RENDER_WAIT_MS = 500
 
 export const tabSnapshot: CliCommand = {
-  args: [{ name: 'tabId', required: true }],
+  args: [{ complete: { kind: 'dynamic', source: 'tab' }, name: 'tabId', required: true }],
   flags: [
     ...SHARED_FLAGS,
     { description: 'return only the last N non-blank lines', kind: 'number', name: 'tail' },
     {
+      complete: { kind: 'values', values: ['json', 'text'] },
       description: 'output format: json (default) or text (raw screen dump)',
       kind: 'string',
       name: 'format',

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

@@ -21,7 +21,7 @@ function toCursor(snapshot: TerminalSnapshot): Cursor {
 }
 
 export const tabTail: CliCommand = {
-  args: [{ name: 'tabId', required: true }],
+  args: [{ complete: { kind: 'dynamic', source: 'tab' }, name: 'tabId', required: true }],
   flags: [
     ...SHARED_FLAGS,
     {

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

@@ -12,10 +12,11 @@ function isTabActivity(value: string): value is TabActivity {
 }
 
 export const tabWait: CliCommand = {
-  args: [{ name: 'tabId', required: true }],
+  args: [{ complete: { kind: 'dynamic', source: 'tab' }, name: 'tabId', required: true }],
   flags: [
     ...SHARED_FLAGS,
     {
+      complete: { kind: 'values', values: ['idle', 'waiting-input', 'working'] },
       description: 'target activity (idle | working | waiting-input)',
       kind: 'string',
       name: 'status',

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

@@ -5,27 +5,28 @@ import { writeJson } from '../../output'
 import { DEFAULT_TIMEOUT_MS } from '../tab/await-turn'
 import {
   awaitExistingWorker,
-  resolveWorkerTab,
+  resolveWorkerTarget,
   workerEnvelope,
   workerOutcomeExitCode,
   workerView,
 } from './shared'
 
 export const workerAwait: CliCommand = {
-  args: [{ name: 'worker', required: true }],
+  args: [{ complete: { kind: 'dynamic', source: 'worker' }, 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 { tab, workspace } = await resolveWorkerTarget(ctx, ctx.args.positionals[0] ?? '')
     const outcome = await awaitExistingWorker(
       ctx,
+      workspace,
       tab.id,
       typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_TIMEOUT_MS
     )
-    writeJson(workerEnvelope(workerView(ctx, tab), outcome))
+    writeJson(workerEnvelope(workspace, workerView(workspace, tab), outcome))
     return workerOutcomeExitCode(outcome)
   },
   summary: "Await an existing worker's in-flight turn",

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

@@ -18,6 +18,11 @@ import {
   isCommandAvailable,
   parseCommand,
 } from '../../../pty/command-registry'
+import {
+  findPrimaryWorktree,
+  WORKSPACE_ENV_VAR,
+  workspaceRepoRoot,
+} from '../../client/workspace-resolver'
 import { SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, EXIT_RUNTIME, writeJson } from '../../output'
 import { WORKER_SCHEMA_VERSION } from './shared'
@@ -56,7 +61,8 @@ export const workerDoctor: CliCommand = {
     const missingManagerCapabilities = [MANAGER_CAPABILITY_WORKER_METADATA].filter(
       (capability) => !managerCapabilities.includes(capability)
     )
-    const primaryWorktree = workspace.worktrees?.find((worktree) => worktree.source === 'primary')
+    const primaryWorktree = findPrimaryWorktree(workspace)
+    const workspaceOrigin = ctx.getWorkspaceOrigin?.() ?? 'active'
     const availableAssistants = assistants.filter((assistant) => assistant.available)
     const skillPath = fileURLToPath(
       new URL('../../../../skills/aimux-orchestrator/', import.meta.url)
@@ -81,6 +87,16 @@ export const workerDoctor: CliCommand = {
     if (!existsSync(skillPath)) {
       issues.push(`packaged orchestrator skill is missing: ${skillPath}`)
     }
+    // Not an issue — an inferred workspace is the normal interactive case — but
+    // it IS the one resolution mode that can follow the UI to another project
+    // between two calls. An orchestrator dispatching a multi-hour fleet wants to
+    // see this before it starts, not after it reviews diffs from the wrong repo.
+    const warnings: string[] = []
+    if (workspaceOrigin === 'active') {
+      warnings.push(
+        `workspace "${workspace.name}" was inferred from the most recently opened session and follows the UI; pin it with --workspace or ${WORKSPACE_ENV_VAR}`
+      )
+    }
     const ready = issues.length === 0
     writeJson({
       assistants,
@@ -100,7 +116,12 @@ export const workerDoctor: CliCommand = {
         skill: { ok: existsSync(skillPath), path: skillPath },
         workspace: {
           hasPrimaryWorktree: primaryWorktree !== undefined,
+          name: workspace.name,
           ok: primaryWorktree !== undefined,
+          /** Repo every fresh worker worktree is cut from — confirm before dispatching. */
+          repoRoot: workspaceRepoRoot(workspace),
+          /** 'flag' | 'env' | 'active'; only 'active' can follow the UI. */
+          source: workspaceOrigin,
         },
       },
       cliVersion: version,
@@ -116,10 +137,13 @@ export const workerDoctor: CliCommand = {
       ready,
       schemaVersion: WORKER_SCHEMA_VERSION,
       skillPath,
+      warnings,
       workspace: {
         id: workspace.id,
         name: workspace.name,
         projectPath: workspace.projectPath ?? null,
+        repoRoot: workspaceRepoRoot(workspace),
+        source: workspaceOrigin,
       },
     })
     return ready ? EXIT_OK : EXIT_RUNTIME

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

@@ -1,22 +1,64 @@
 import type { CliCommand } from '../../registry'
 
+import { workspaceIdentity } from '../../client/workspace-resolver'
 import { SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, writeJson } from '../../output'
-import { listNamedWorkerTabs, resolveWorkerTab, WORKER_SCHEMA_VERSION, workerView } from './shared'
+import {
+  listNamedWorkerTabs,
+  listWorkerTargets,
+  resolveWorkerTarget,
+  WORKER_SCHEMA_VERSION,
+  workerView,
+} from './shared'
 
 export const workerList: CliCommand = {
-  args: [{ name: 'worker' }],
-  flags: SHARED_FLAGS,
+  args: [{ complete: { kind: 'dynamic', source: 'worker' }, name: 'worker' }],
+  flags: [
+    ...SHARED_FLAGS,
+    {
+      description: 'list workers in every catalogued workspace, not just the target one',
+      kind: 'boolean',
+      name: 'all-workspaces',
+    },
+  ],
   group: 'worker',
   run: async (ctx) => {
     const selector = ctx.args.positionals[0]
-    const tabs =
-      selector === undefined
-        ? await listNamedWorkerTabs(ctx)
-        : [await resolveWorkerTab(ctx, selector)]
+
+    // `{"workers":[]}` alone is indistinguishable from "every worker died", and
+    // the natural recovery from that reading is a destructive re-dispatch. Name
+    // the workspace that was queried so an empty fleet is legible as "not here"
+    // rather than "gone", and offer one call that answers "are they really gone?"
+    if (ctx.args.flags['all-workspaces'] === true) {
+      const targets = await listWorkerTargets(ctx)
+      writeJson({
+        schemaVersion: WORKER_SCHEMA_VERSION,
+        workers: targets
+          .filter((target) => selector === undefined || target.tab.workerName === selector)
+          .map((target) => ({
+            ...workerView(target.workspace, target.tab),
+            workspace: workspaceIdentity(target.workspace),
+          })),
+      })
+      return EXIT_OK
+    }
+
+    if (selector !== undefined) {
+      const { tab, workspace } = await resolveWorkerTarget(ctx, selector)
+      writeJson({
+        schemaVersion: WORKER_SCHEMA_VERSION,
+        workers: [workerView(workspace, tab)],
+        workspace: workspaceIdentity(workspace),
+      })
+      return EXIT_OK
+    }
+
+    const workspace = ctx.getWorkspace()
+    const tabs = await listNamedWorkerTabs(ctx, workspace)
     writeJson({
       schemaVersion: WORKER_SCHEMA_VERSION,
-      workers: tabs.map((tab) => workerView(ctx, tab)),
+      workers: tabs.map((tab) => workerView(workspace, tab)),
+      workspace: workspaceIdentity(workspace),
     })
     return EXIT_OK
   },