@brimveyn/aimux 1.21.0 → 1.22.2

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

@@ -3,10 +3,10 @@ import type { CliCommand } from '../../registry'
 import { isGitWorktreeDirty, removeGitWorktree } from '../../../git/worktree'
 import {
   IPC_CAPABILITY_THIN_ATTACH,
-  IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS,
+  IPC_CAPABILITY_WORKSPACE_LIFECYCLE_EVENTS,
 } from '../../../ipc/protocol'
 import { pruneEmptyWorktreeParent } from '../../../platform/worktree-paths'
-import { workspaceIdentity } from '../../client/workspace-resolver'
+import { projectIdentity } from '../../client/project-resolver'
 import { SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, EXIT_RUNTIME, writeJson } from '../../output'
 import { resolveWorkerTarget, WORKER_SCHEMA_VERSION, workerView } from './shared'
@@ -16,45 +16,45 @@ export const workerStop: CliCommand = {
   flags: [
     ...SHARED_FLAGS,
     {
-      description: 'remove its aimux-created worktree after closing the tab',
+      description: 'remove its aimux-created workspace after closing the tab',
       kind: 'boolean',
-      name: 'cleanup-worktree',
+      name: 'cleanup-workspace',
     },
-    { description: 'force removal of a dirty worktree', kind: 'boolean', name: 'force' },
+    { description: 'force removal of a dirty workspace', kind: 'boolean', name: 'force' },
   ],
   group: 'worker',
   run: async (ctx) => {
-    const { tab, workspace } = await resolveWorkerTarget(ctx, ctx.args.positionals[0] ?? '')
-    const worker = workerView(workspace, tab)
+    const { project, tab } = await resolveWorkerTarget(ctx, ctx.args.positionals[0] ?? '')
+    const worker = workerView(project, tab)
     const daemon = await ctx.getDaemon()
-    const cleanup = ctx.args.flags['cleanup-worktree'] === true
+    const cleanup = ctx.args.flags['cleanup-workspace'] === true
     const record =
-      tab.worktreeId === undefined
+      tab.workspaceId === undefined
         ? undefined
-        : workspace.worktrees?.find((worktree) => worktree.id === tab.worktreeId)
+        : project.workspaces?.find((workspace) => workspace.id === tab.workspaceId)
 
     if (cleanup) {
-      if (record === undefined) throw new Error('worker has no registered worktree to clean up')
+      if (record === undefined) throw new Error('worker has no registered workspace to clean up')
       if (record.source !== 'aimux-temp' || !record.createdByAimux) {
-        throw new Error('refusing to clean up a primary or externally managed worktree')
+        throw new Error('refusing to clean up a primary or externally managed workspace')
       }
-      const siblings = (await daemon.listTabs(workspace.id)).tabs.filter(
-        (entry) => entry.id !== tab.id && entry.worktreeId === record.id
+      const siblings = (await daemon.listTabs(project.id)).tabs.filter(
+        (entry) => entry.id !== tab.id && entry.workspaceId === record.id
       )
       if (siblings.length > 0) {
         throw new Error(
-          `refusing to clean up shared worktree; live tabs: ${siblings.map((entry) => entry.id).join(', ')}`
+          `refusing to clean up shared workspace; 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 (!daemon.hasCapability(IPC_CAPABILITY_WORKSPACE_LIFECYCLE_EVENTS)) {
+        throw new Error('daemon predates safe workspace 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')
+        throw new Error('refusing to clean up a dirty workspace without --force')
       }
     }
 
-    // `closeTab` is session-scoped on the daemon, so it fails with "No session
+    // `closeTab` is project-scoped on the daemon, so it fails with "No project
     // attached" unless this connection has attached first. Every other worker
     // verb thin-attaches; this one did not, which made teardown the one step of
     // the documented lifecycle a headless orchestrator could not complete.
@@ -63,10 +63,10 @@ export const workerStop: CliCommand = {
         'daemon predates thinAttach capability — restart aimux to pick up the new daemon'
       )
     }
-    await daemon.attach({ cols: 0, rows: 0, sessionId: workspace.id, thin: true })
+    await daemon.attach({ cols: 0, projectId: project.id, rows: 0, thin: true })
 
     // Teardown is two independent effects. Report them independently: a failed
-    // tab close must not strand a merged worktree on disk with no way to remove
+    // tab close must not strand a merged workspace on disk with no way to remove
     // it through aimux (the alternative — a bare `git worktree remove` — desyncs
     // the catalog from disk).
     let closeError: string | undefined
@@ -77,7 +77,7 @@ export const workerStop: CliCommand = {
       if (!cleanup) throw error
     }
 
-    let worktreeRemoved = false
+    let workspaceRemoved = false
     if (cleanup && record !== undefined) {
       await removeGitWorktree({
         force: ctx.args.flags.force === true,
@@ -86,9 +86,9 @@ export const workerStop: CliCommand = {
       })
       await pruneEmptyWorktreeParent(record.path)
       try {
-        await daemon.expectOk('removeWorktreeRecord', {
-          sessionId: workspace.id,
-          worktreeId: record.id,
+        await daemon.expectOk('removeWorkspaceRecord', {
+          projectId: project.id,
+          workspaceId: record.id,
         })
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error)
@@ -96,18 +96,18 @@ export const workerStop: CliCommand = {
           `worker stopped and git worktree removed, but catalog reconciliation failed: ${message}`
         )
       }
-      worktreeRemoved = true
+      workspaceRemoved = true
     }
     writeJson({
       closed: closeError === undefined,
       ...(closeError === undefined ? {} : { closeError }),
+      project: projectIdentity(project),
       schemaVersion: WORKER_SCHEMA_VERSION,
       worker,
-      workspace: workspaceIdentity(workspace),
-      worktreeRemoved,
+      workspaceRemoved,
     })
     return closeError === undefined ? EXIT_OK : EXIT_RUNTIME
   },
-  summary: 'Stop a named worker and optionally clean up its worktree',
+  summary: 'Stop a named worker and optionally clean up its workspace',
   verb: 'stop',
 }

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

@@ -23,16 +23,16 @@ export const workerSubmit: CliCommand = {
   ],
   group: 'worker',
   run: async (ctx) => {
-    const { tab, workspace } = await resolveWorkerTarget(ctx, ctx.args.positionals[0] ?? '')
+    const { project, tab } = await resolveWorkerTarget(ctx, ctx.args.positionals[0] ?? '')
     const outcome = await submitWorkerPrompt(
       ctx,
-      workspace,
+      project,
       tab.id,
       typeof ctx.args.flags['uptake-timeout'] === 'number'
         ? ctx.args.flags['uptake-timeout']
         : DETACH_UPTAKE_TIMEOUT_MS
     )
-    writeJson(workerEnvelope(workspace, workerView(workspace, tab), outcome))
+    writeJson(workerEnvelope(project, workerView(project, tab), outcome))
     return workerOutcomeExitCode(outcome)
   },
   summary: 'Submit a prompt already sitting in a worker composer and confirm uptake',

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,