@brimveyn/aimux 1.20.4 → 1.22.0

package/src/cli/commands/{worktree → workspace}/create-core.ts

@@ -1,8 +1,8 @@
-import type { SessionRecord, WorktreeRecord } from '../../../state/types'
+import type { ProjectRecord, WorkspaceRecord } from '../../../state/types'
 import type { DaemonClient } from '../../client/daemon-client'
 
 import { createGitWorktree, removeGitWorktree, resolveGitRef } from '../../../git/worktree'
-import { IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS } from '../../../ipc/protocol'
+import { IPC_CAPABILITY_WORKSPACE_LIFECYCLE_EVENTS } from '../../../ipc/protocol'
 import { createPrefixedId } from '../../../platform/id'
 import {
   assertSafeAimuxWorktreePath,
@@ -11,59 +11,59 @@ import {
   pruneEmptyWorktreeParent,
 } from '../../../platform/worktree-paths'
 
-export interface CreateWorktreeParams {
+export interface CreateWorkspaceParams {
   /** Base ref for the branch (callers default to 'HEAD'). */
   base: string
   /** Branch name (callers default to `aimux/<name>`). */
   branch: string
   daemon: DaemonClient
   name: string
-  workspace: SessionRecord
+  project: ProjectRecord
 }
 
 /**
- * Create a git worktree + its catalog record for a workspace. Shared by
- * `worktree create` and `tab create --new-worktree`. Checks the daemon
- * capability BEFORE touching disk, and rolls back the on-disk worktree if
+ * Create a git worktree + its catalog record for a project. Shared by
+ * `workspace create` and `tab create --new-workspace`. Checks the daemon
+ * capability BEFORE touching disk, and rolls back the on-disk workspace if
  * catalog registration fails (so `worktree list` never surfaces an orphan).
  * Throws on any failure; returns the registered record on success.
  */
-export async function createWorkspaceWorktree(
-  params: CreateWorktreeParams
-): Promise<WorktreeRecord> {
-  const { base, branch, daemon, name, workspace } = params
+export async function createProjectWorkspace(
+  params: CreateWorkspaceParams
+): Promise<WorkspaceRecord> {
+  const { base, branch, daemon, name, project } = params
 
-  const primary = workspace.worktrees?.find((w) => w.source === 'primary')
+  const primary = project.workspaces?.find((w) => w.source === 'primary')
   if (!primary) {
     throw new Error(
-      `workspace "${workspace.name}" has no primary worktree — set --project when creating it`
+      `project "${project.name}" has no primary workspace — set --project when creating it`
     )
   }
 
   // Check the daemon's capability BEFORE mutating disk — otherwise a capability
   // mismatch would leave a git worktree on disk with no catalog record.
-  if (!daemon.hasCapability(IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS)) {
+  if (!daemon.hasCapability(IPC_CAPABILITY_WORKSPACE_LIFECYCLE_EVENTS)) {
     throw new Error(
-      'daemon predates worktreeLifecycleEvents capability — restart aimux to pick up the new daemon'
+      'daemon predates workspaceLifecycleEvents capability — restart aimux to pick up the new daemon'
     )
   }
 
   // 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
+  // The project decides the repo, so a caller who believes it is orchestrating
+  // project A while the resolved project 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`
+      `base ref "${base}" does not exist in ${primary.repoRoot} (project "${project.name}") — check that this is the repository you meant`
     )
   }
 
-  const worktreeId = createPrefixedId('worktree')
+  const workspaceId = createPrefixedId('workspace')
   const targetPath = makeWorktreePath({
     repoRoot: primary.repoRoot,
-    worktreeId,
-    worktreeName: name,
+    workspaceId,
+    workspaceName: name,
   })
   await ensureAimuxWorktreeRoot()
   await assertSafeAimuxWorktreePath(targetPath)
@@ -83,12 +83,12 @@ export async function createWorkspaceWorktree(
   }
 
   const now = new Date().toISOString()
-  const record: WorktreeRecord = {
+  const record: WorkspaceRecord = {
     baseRef: base,
     branch,
     createdAt: now,
     createdByAimux: true,
-    id: worktreeId,
+    id: workspaceId,
     name,
     path: targetPath,
     repoRoot: primary.repoRoot,
@@ -97,16 +97,16 @@ export async function createWorkspaceWorktree(
   }
 
   try {
-    await daemon.expectOk('addWorktreeRecord', { sessionId: workspace.id, worktree: record })
+    await daemon.expectOk('addWorkspaceRecord', { projectId: project.id, workspace: record })
   } catch (error) {
-    // Catalog registration failed — roll back the on-disk worktree so
+    // Catalog registration failed — roll back the on-disk workspace so
     // `worktree list` doesn't perpetually surface an orphan. Swallow rollback
     // 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
+      // Best-effort rollback; leave the git-side workspace if it can't be removed
       // cleanly. `worktree list` will flag it as gitTracked with no catalog.
     }
     throw error

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

@@ -1,93 +1,55 @@
-import { resolve as resolvePath } from 'node:path'
-
 import type { CliCommand } from '../../registry'
 
-import { IPC_CAPABILITY_WORKSPACE_LIFECYCLE } from '../../../ipc/protocol'
 import { SHARED_FLAGS } from '../../flags'
-import { EXIT_OK, EXIT_TIMEOUT, writeJson } from '../../output'
-
-const DEFAULT_WAIT_TIMEOUT_MS = 30_000
+import { EXIT_OK, writeJson } from '../../output'
+import { createProjectWorkspace } from './create-core'
 
 export const workspaceCreate: CliCommand = {
-  args: [{ complete: { kind: 'none' }, name: 'name', required: true }],
+  args: [],
   flags: [
     ...SHARED_FLAGS,
     {
-      complete: { kind: 'file' },
-      description: 'project path to associate with the workspace',
+      complete: { kind: 'none' },
+      description: 'display name for the new workspace',
       kind: 'string',
-      name: 'project',
-    },
-    {
-      description: 'immediately switch the running UI to the new workspace',
-      kind: 'boolean',
-      name: 'switch',
+      name: 'name',
     },
     {
-      description: 'with --switch, wait until the UI confirms the switch completed',
-      kind: 'boolean',
-      name: 'wait',
+      complete: { kind: 'none' },
+      description: 'branch name (defaults to aimux/<name>)',
+      kind: 'string',
+      name: 'branch',
     },
     {
-      description: 'timeout for --wait, in milliseconds (default 30000)',
-      kind: 'number',
-      name: 'timeout',
+      complete: { kind: 'dynamic', source: 'git-ref' },
+      description: 'base ref for the branch (defaults to HEAD)',
+      kind: 'string',
+      name: 'base',
     },
   ],
   group: 'workspace',
   run: async (ctx) => {
-    const name = ctx.args.positionals[0]
+    const name = ctx.args.flags.name
     if (typeof name !== 'string' || name.length === 0) {
-      throw new Error('workspace name is required')
-    }
-    const projectRaw =
-      typeof ctx.args.flags.project === 'string' ? ctx.args.flags.project : undefined
-    const projectPath = projectRaw === undefined ? undefined : resolvePath(projectRaw)
-    const doSwitch = ctx.args.flags.switch === true
-    const wait = ctx.args.flags.wait === true
-    const timeoutMs =
-      typeof ctx.args.flags.timeout === 'number' ? ctx.args.flags.timeout : DEFAULT_WAIT_TIMEOUT_MS
-
-    if (wait && !doSwitch) {
-      // Without --switch, the UI never emits an ack event, so there's
-      // nothing meaningful for --wait to wait on.
-      throw new Error('--wait requires --switch (nothing to wait for otherwise)')
+      throw new Error('--name is required')
     }
+    const branch =
+      typeof ctx.args.flags.branch === 'string' ? ctx.args.flags.branch : `aimux/${name}`
+    const base = typeof ctx.args.flags.base === 'string' ? ctx.args.flags.base : 'HEAD'
 
+    const project = ctx.getProject()
     const daemon = await ctx.getDaemon()
-    if (!daemon.hasCapability(IPC_CAPABILITY_WORKSPACE_LIFECYCLE)) {
-      throw new Error(
-        'daemon predates workspaceLifecycle capability — restart aimux to pick up the new daemon'
-      )
-    }
-
-    if (!wait) {
-      await daemon.expectOk('createWorkspace', { name, projectPath, switch: doSwitch })
-      writeJson({ name, projectPath, switch: doSwitch })
-      return EXIT_OK
-    }
-
-    // Subscribe BEFORE sending the request. The UI's create+switch path
-    // relays as `workspaceSwitched` once handleCreateSessionEffect has
-    // dispatched load-session. Match on name+projectPath since the CLI
-    // doesn't know the id the UI will assign to the new session.
-    const settled = new Promise<number>((resolve) => {
-      const off = daemon.on('workspaceSwitched', (payload) => {
-        off()
-        clearTimeout(timer)
-        writeJson({ name, projectPath, sessionId: payload.sessionId, switch: doSwitch })
-        resolve(EXIT_OK)
-      })
-      const timer = setTimeout(() => {
-        off()
-        writeJson({ error: 'timed out waiting for workspaceSwitched', name, projectPath })
-        resolve(EXIT_TIMEOUT)
-      }, timeoutMs)
+    const record = await createProjectWorkspace({ base, branch, daemon, name, project })
+
+    writeJson({
+      branch: record.branch,
+      id: record.id,
+      name: record.name,
+      path: record.path,
+      repoRoot: record.repoRoot,
     })
-
-    await daemon.expectOk('createWorkspace', { name, projectPath, switch: doSwitch })
-    return settled
+    return EXIT_OK
   },
-  summary: 'Create a new workspace (via the UI when attached, otherwise the catalog)',
+  summary: 'Create a new workspace in the active project',
   verb: 'create',
 }

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

@@ -1,6 +1,7 @@
 import type { CliCommand } from '../../registry'
 
-import { listWorkspaces } from '../../client/workspace-resolver'
+import { listGitWorktrees } from '../../../git/worktree'
+import { IPC_CAPABILITY_LIST_TABS } from '../../../ipc/protocol'
 import { SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, writeJson } from '../../output'
 
@@ -8,18 +9,60 @@ export const workspaceList: CliCommand = {
   args: [],
   flags: SHARED_FLAGS,
   group: 'workspace',
-  run: async () => {
-    const sessions = listWorkspaces()
+  run: async (ctx) => {
+    const project = ctx.getProject()
+    const records = project.workspaces ?? []
+
+    // Count live tabs per workspace so an orchestrator can see co-location
+    // (several workers sharing one workspace) at a glance. Best-effort: `null`
+    // when the daemon is unreachable or predates the listTabs capability —
+    // `worktree list` otherwise reads purely from the catalog + git, so we don't
+    // want a down daemon to fail it.
+    const tabCounts = new Map<string, number>()
+    let tabCountsAvailable = false
+    try {
+      const daemon = await ctx.getDaemon()
+      if (daemon.hasCapability(IPC_CAPABILITY_LIST_TABS)) {
+        const { tabs } = await daemon.listTabs(project.id)
+        for (const tab of tabs) {
+          if (tab.workspaceId != null) {
+            tabCounts.set(tab.workspaceId, (tabCounts.get(tab.workspaceId) ?? 0) + 1)
+          }
+        }
+        tabCountsAvailable = true
+      }
+    } catch {
+      // daemon unreachable — leave tabCount null rather than failing the list.
+    }
+
+    // Cross-check against git so we can flag catalog entries that git no
+    // longer knows about (prunable / vanished) — otherwise the CLI would
+    // happily report workspaces that don't exist on disk.
+    const primary = records.find((w) => w.source === 'primary')
+    const gitPaths = new Set<string>()
+    if (primary) {
+      for (const w of await listGitWorktrees(primary.repoRoot)) {
+        if (w.prunable !== true) gitPaths.add(w.path)
+      }
+    }
+
     writeJson({
-      workspaces: sessions.map((session) => ({
-        id: session.id,
-        lastOpenedAt: session.lastOpenedAt,
-        name: session.name,
-        projectPath: session.projectPath,
+      activeWorkspaceId: project.activeWorkspaceId ?? null,
+      projectId: project.id,
+      workspaces: records.map((w) => ({
+        branch: w.branch,
+        createdByAimux: w.createdByAimux,
+        gitTracked: primary ? gitPaths.has(w.path) : null,
+        id: w.id,
+        name: w.name,
+        path: w.path,
+        repoRoot: w.repoRoot,
+        source: w.source,
+        tabCount: tabCountsAvailable ? (tabCounts.get(w.id) ?? 0) : null,
       })),
     })
     return EXIT_OK
   },
-  summary: 'List known workspaces (sessions) in the profile catalog',
+  summary: 'List workspaces for a project',
   verb: 'list',
 }

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

@@ -0,0 +1,81 @@
+import type { CliCommand } from '../../registry'
+
+import { removeGitWorktree } from '../../../git/worktree'
+import {
+  IPC_CAPABILITY_LIST_TABS,
+  IPC_CAPABILITY_WORKSPACE_LIFECYCLE_EVENTS,
+} from '../../../ipc/protocol'
+import { pruneEmptyWorktreeParent } from '../../../platform/worktree-paths'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const workspaceRemove: CliCommand = {
+  args: [{ complete: { kind: 'dynamic', source: 'workspace' }, name: 'workspace', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    { description: 'pass --force to git worktree remove', kind: 'boolean', name: 'force' },
+  ],
+  group: 'workspace',
+  run: async (ctx) => {
+    const target = ctx.args.positionals[0]
+    if (typeof target !== 'string' || target.length === 0) {
+      throw new Error('workspace id or path is required')
+    }
+    const force = ctx.args.flags.force === true
+
+    const project = ctx.getProject()
+    const workspace =
+      project.workspaces?.find((w) => w.id === target) ??
+      project.workspaces?.find((w) => w.path === target)
+    if (!workspace) {
+      const known = project.workspaces?.map((w) => w.id).join(', ') ?? '(none)'
+      throw new Error(`unknown workspace: ${target} (known: ${known})`)
+    }
+    if (workspace.source === 'primary') {
+      throw new Error('refusing to remove the primary workspace')
+    }
+
+    const primary = project.workspaces?.find((w) => w.source === 'primary')
+    if (!primary) {
+      throw new Error('project has no primary workspace — cannot resolve repoRoot for git remove')
+    }
+
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_WORKSPACE_LIFECYCLE_EVENTS)) {
+      throw new Error(
+        'daemon predates workspaceLifecycleEvents capability — restart aimux to pick up the new daemon'
+      )
+    }
+    if (daemon.hasCapability(IPC_CAPABILITY_LIST_TABS)) {
+      const live = (await daemon.listTabs(project.id)).tabs.filter(
+        (tab) => tab.workspaceId === workspace.id
+      )
+      if (live.length > 0) {
+        throw new Error(
+          `refusing to remove workspace with live tabs: ${live.map((tab) => tab.id).join(', ')}`
+        )
+      }
+    }
+
+    // All capability and liveness checks happen before touching git. If git
+    // refuses a dirty workspace the catalog remains unchanged.
+    await removeGitWorktree({ force, repoPath: primary.repoRoot, targetPath: workspace.path })
+    await pruneEmptyWorktreeParent(workspace.path)
+    try {
+      await daemon.expectOk('removeWorkspaceRecord', {
+        projectId: project.id,
+        workspaceId: workspace.id,
+      })
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      throw new Error(
+        `worktree removed from git but catalog reconciliation failed for ${workspace.id}: ${message}`
+      )
+    }
+
+    writeJson({ id: workspace.id, name: workspace.name, path: workspace.path })
+    return EXIT_OK
+  },
+  summary: 'Remove a workspace from the active project',
+  verb: 'remove',
+}

package/src/cli/completion/plan.ts

@@ -51,10 +51,10 @@ const COMPLETION_SUBCOMMANDS: readonly CompletionCandidate[] = [
 ]
 
 const GROUP_DESCRIPTIONS: Record<string, string> = {
+  project: 'Projects (projects) in the profile catalog',
   tab: 'Drive individual tabs (create, send, snapshot, await)',
   worker: 'Named agent workers — the preferred orchestration surface',
-  workspace: 'Workspaces (sessions) in the profile catalog',
-  worktree: 'Git worktrees attached to the active workspace',
+  workspace: 'Git workspaces attached to the active project',
 }
 
 function groupCandidates(): CompletionCandidate[] {

package/src/cli/completion/sources.ts

@@ -8,8 +8,8 @@
  *     shell must never see a stack trace where a completion list belongs.
  *
  * Phase 1 implements only the sources that read local state (built-in
- * assistants, the workspace catalog). Daemon-backed sources — tabs, workers,
- * worktrees — and git refs return nothing until phase 2 wires them up.
+ * assistants, the project catalog). Daemon-backed sources — tabs, workers,
+ * workspaces — and git refs return nothing until phase 2 wires them up.
  */
 
 import type { DynamicCompletionSource } from '../flags'
@@ -24,20 +24,20 @@ function assistantCandidates(): CompletionCandidate[] {
   }))
 }
 
-async function workspaceCandidates(): Promise<CompletionCandidate[]> {
-  // Imported lazily: the session catalog pulls in config + state modules that
+async function projectCandidates(): Promise<CompletionCandidate[]> {
+  // Imported lazily: the project catalog pulls in config + state modules that
   // the static-source paths (groups, verbs, flags) have no reason to load.
-  const { listWorkspaces } = await import('../client/workspace-resolver')
-  const sessions = listWorkspaces()
+  const { listProjects } = await import('../client/project-resolver')
+  const projects = listProjects()
   const nameCounts = new Map<string, number>()
-  for (const session of sessions) {
-    nameCounts.set(session.name, (nameCounts.get(session.name) ?? 0) + 1)
+  for (const project of projects) {
+    nameCounts.set(project.name, (nameCounts.get(project.name) ?? 0) + 1)
   }
-  return sessions.map((session) =>
-    // Ambiguous names can't be resolved by `--workspace`, so offer the id.
-    (nameCounts.get(session.name) ?? 0) > 1
-      ? { description: session.name, value: session.id }
-      : { description: session.id, value: session.name }
+  return projects.map((project) =>
+    // Ambiguous names can't be resolved by `--project`, so offer the id.
+    (nameCounts.get(project.name) ?? 0) > 1
+      ? { description: project.name, value: project.id }
+      : { description: project.id, value: project.name }
   )
 }
 
@@ -45,10 +45,10 @@ async function resolveSource(source: DynamicCompletionSource): Promise<Completio
   switch (source) {
     case 'assistant':
       return assistantCandidates()
-    case 'workspace':
-      return await workspaceCandidates()
-    // Phase 2: 'tab' | 'worker' | 'worktree' need a daemon round-trip under a
-    // deadline; 'git-ref' needs a `git for-each-ref` in the workspace repo.
+    case 'project':
+      return await projectCandidates()
+    // Phase 2: 'tab' | 'worker' | 'workspace' need a daemon round-trip under a
+    // deadline; 'git-ref' needs a `git for-each-ref` in the project repo.
     default:
       return []
   }
@@ -56,7 +56,7 @@ async function resolveSource(source: DynamicCompletionSource): Promise<Completio
 
 /**
  * Resolve a dynamic source, filter by the partial word, and re-apply the
- * prefix the planner stripped (e.g. `--workspace=`). Always resolves.
+ * prefix the planner stripped (e.g. `--project=`). Always resolves.
  */
 export async function resolveDynamicCandidates(
   source: DynamicCompletionSource,

package/src/cli/context.ts

@@ -1,31 +1,31 @@
-import type { SessionRecord } from '../state/types'
+import type { ProjectRecord } from '../state/types'
 import type { DaemonClient } from './client/daemon-client'
-import type { WorkspaceOrigin } from './client/workspace-resolver'
+import type { ProjectOrigin } from './client/project-resolver'
 import type { ParsedArgs } from './flags'
 
 /**
  * Per-command context handed to `CliCommand.run`. Commands lazily resolve
- * the workspace + daemon via the helpers on this object so a command that
- * only reads flags (e.g. `workspace list`) doesn't have to open a socket.
+ * the project + daemon via the helpers on this object so a command that
+ * only reads flags (e.g. `project list`) doesn't have to open a socket.
  */
 export interface CliContext {
   args: ParsedArgs
   /** Already-running daemon client, populated on first call to `daemon()`. */
   getDaemon: () => Promise<DaemonClient>
-  /** Resolved workspace, populated on first call to `workspace()`. */
-  getWorkspace: () => SessionRecord
+  /** Resolved project, populated on first call to `project()`. */
+  getProject: () => ProjectRecord
   /**
-   * Every catalogued workspace. Commands that must answer "is my worker really
-   * gone, or did the active workspace move?" need the whole catalog, not just
+   * Every catalogued project. Commands that must answer "is my worker really
+   * gone, or did the active project move?" need the whole catalog, not just
    * the resolved record. Optional so test fixtures can inject one.
    */
-  getWorkspaces?: () => SessionRecord[]
+  getProjects?: () => ProjectRecord[]
   /**
-   * Where `getWorkspace()` came from — `flag` (`--workspace`), `env`
-   * (`AIMUX_WORKSPACE`), or `active` (most recently opened session). Only
-   * `active` can drift under a command while the UI switches workspaces, so
+   * Where `getProject()` came from — `flag` (`--project`), `env`
+   * (`AIMUX_PROJECT`), or `active` (most recently opened project). Only
+   * `active` can drift under a command while the UI switches projects, so
    * commands that must not follow the UI branch on this. Optional so test
    * fixtures can build a minimal context.
    */
-  getWorkspaceOrigin?: () => WorkspaceOrigin
+  getProjectOrigin?: () => ProjectOrigin
 }

package/src/cli/flags.ts

@@ -15,8 +15,8 @@ export type DynamicCompletionSource =
   | 'git-ref'
   | 'tab'
   | 'worker'
+  | 'project'
   | 'workspace'
-  | 'worktree'
 
 /**
  * Where a flag value or positional draws its shell-completion candidates.
@@ -67,6 +67,23 @@ export function parseArgs(
 ): ParsedArgs {
   const flagByName = new Map<string, FlagSpec>()
   for (const spec of flagSpecs) flagByName.set(spec.name, spec)
+  // Deprecated aliases from the project/workspace rename. Unlike the command
+  // groups these are safe to map silently: --workspace named a project and
+  // --worktree named what is now a workspace, so each old name still points at
+  // the same object.
+  // ponytail: drop with the aimux-sessions.json fallback.
+  // Resolved against the declared specs, never against another alias —
+  // otherwise --worktree would chain through the --workspace alias onto
+  // --project, which is a different object entirely.
+  for (const [old, current] of [
+    ['workspace', 'project'],
+    ['worktree', 'workspace'],
+    ['new-worktree', 'new-workspace'],
+  ] as const) {
+    if (flagByName.has(old)) continue
+    const spec = flagSpecs.find((entry) => entry.name === current)
+    if (spec) flagByName.set(old, spec)
+  }
 
   const flags: Record<string, string | number | boolean> = {}
   const positionals: string[] = []
@@ -85,18 +102,21 @@ export function parseArgs(
       if (!spec) {
         throw new CliUsageError(`unknown flag: --${name}`)
       }
+      // Deprecated aliases resolve to the current spec, so results are always
+      // keyed by the canonical name regardless of which spelling was typed.
+      const key = spec.name
       if (spec.kind === 'boolean') {
         if (eq !== -1) {
           throw new CliUsageError(`flag --${name} does not take a value`)
         }
-        flags[name] = true
+        flags[key] = true
         continue
       }
       if (spec.kind === 'optional-string') {
         // Value binds ONLY in the `=` form (`--flag=value`). A bare `--flag`
         // must not swallow the next token (it may be a positional), so it
         // parses as boolean `true`.
-        flags[name] = eq === -1 ? true : token.slice(eq + 1)
+        flags[key] = eq === -1 ? true : token.slice(eq + 1)
         continue
       }
       const raw = eq === -1 ? argv[++i] : token.slice(eq + 1)
@@ -108,9 +128,9 @@ export function parseArgs(
         if (!Number.isFinite(parsed)) {
           throw new CliUsageError(`flag --${name} must be a number (got: ${raw})`)
         }
-        flags[name] = parsed
+        flags[key] = parsed
       } else {
-        flags[name] = raw
+        flags[key] = raw
       }
       continue
     }
@@ -129,17 +149,17 @@ export function parseArgs(
 }
 
 /**
- * Shared flag set — every command takes these. `--workspace` selects the
- * target session (by id or name); `--profile` overrides `AIMUX_PROFILE`
+ * Shared flag set — every command takes these. `--project` selects the
+ * target project (by id or name); `--profile` overrides `AIMUX_PROFILE`
  * before any runtime path is resolved; `--json` is a no-op kept for
  * consistency with future formats.
  */
 export const SHARED_FLAGS: readonly FlagSpec[] = [
   {
-    complete: { kind: 'dynamic', source: 'workspace' },
-    description: 'workspace id or name',
+    complete: { kind: 'dynamic', source: 'project' },
+    description: 'project id or name',
     kind: 'string',
-    name: 'workspace',
+    name: 'project',
   },
   {
     complete: { kind: 'none' },