@brimveyn/aimux 1.21.0 → 1.22.2

package/src/app.tsx

@@ -1,4 +1,5 @@
 import {
+  type AimuxUserConfig,
   type ResolvedConfig,
   setAutoCommitEnabled,
   setExternalEditorConfig,
@@ -8,20 +9,23 @@ import {
 import { useKeyboard, useRenderer, useTerminalDimensions } from '@opentui/react'
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
 
+import type { SideEffectContext } from './app-runtime/side-effect-context'
 import type { KeyChord } from './input/keymap/key-chord'
 import type { TrieBinding } from './input/keymap/trie'
 import type { KeyResult, ModeContext, ModeId } from './input/modes/types'
 import type { TerminalContentOrigin } from './input/raw-input-handler'
 import type { SessionBackend } from './session-backend/types'
 
-import { executeSideEffect, type SideEffectContext } from './app-runtime/side-effects'
+import { setActiveMeasure } from './app-runtime/measure-ref'
+import { executeSideEffect } from './app-runtime/side-effects'
 import { useAutoCommitDriver } from './app-runtime/use-auto-commit-driver'
 import { useBackendRuntime } from './app-runtime/use-backend-runtime'
 import { useDirectorySearch } from './app-runtime/use-directory-search'
 import { useMouseHandlers } from './app-runtime/use-mouse-handlers'
+import { useProjectAutosave } from './app-runtime/use-project-autosave'
 import { useRendererBindings } from './app-runtime/use-renderer-bindings'
+import { useSetupRunner } from './app-runtime/use-setup-runner'
 import { useTerminalResize } from './app-runtime/use-terminal-resize'
-import { useWorkspaceAutosave } from './app-runtime/use-workspace-autosave'
 import { loadConfig, saveConfig } from './config'
 import { enqueueGitOp } from './git/command-queue'
 import { pruneOrphanAimuxBranches } from './git/worktree'
@@ -34,11 +38,19 @@ import { highlightSnapshot, warmClaudeSyntaxOverlay } from './integrations/claud
 import { ensureClaudeSettingsThemePref, syncClaudeTheme } from './integrations/claude-theme-sync'
 import { getProfileConfigDir, getProfileName } from './profile-paths'
 import { startAIUsageService } from './services/ai-usage/provider'
+import {
+  useAIUsageConfig,
+  useAutoCommitConfig,
+  useHarmonizeClaudeTheme,
+  useSnippetTriggerChar,
+} from './settings/live'
+import { ALL_SETTING_ROWS } from './settings/sections'
+import { hydrateSettings } from './settings/settings-store'
 import { aiUsageStore } from './state/ai-usage-store'
 import { appStore, useAppStore } from './state/app-store'
 import { setActiveDispatch, setActiveSideEffectRunner } from './state/dispatch-ref'
-import { findMostRecentSession, loadSessionCatalog } from './state/session-catalog'
-import { getSessionProjectPath } from './state/session-worktrees'
+import { findMostRecentProject, loadProjectCatalog } from './state/project-catalog'
+import { getActiveWorkspacePath } from './state/project-workspaces'
 import { loadSnippetCatalog, mergeConfigSnippets } from './state/snippet-catalog'
 import { createInitialState } from './state/store'
 import { toast } from './state/toast-store'
@@ -59,14 +71,16 @@ import {
   isNewerVersion,
 } from './update/version-check'
 
-const WORKSPACE_SAVE_DEBOUNCE_MS = 250
+const PROJECT_SAVE_DEBOUNCE_MS = 250
 
 export function App({
   backend,
   resolvedConfig,
+  userConfig,
 }: {
   backend: SessionBackend
   resolvedConfig: ResolvedConfig
+  userConfig: AimuxUserConfig
 }) {
   // Publish the auto-commit enabled flag before any children render so
   // actions (which live outside React) can read it synchronously.
@@ -104,8 +118,8 @@ export function App({
   // selector reads. We discard the value — the store is the source of truth.
   useState(() => {
     const json = loadConfig()
-    const sessionBarVisible =
-      resolvedConfig.sessionBar?.initialVisible ?? json.sessionBarVisible ?? true
+    const projectBarVisible =
+      resolvedConfig.projectBar?.initialVisible ?? json.projectBarVisible ?? true
     // Merge config-file gitPane (persisted prefs) with user's resolved gitPane
     // (programmatic config). User config wins; file provides persisted prior state.
     const userGitPane = resolvedConfig.gitPane
@@ -118,32 +132,28 @@ export function App({
       ...(userGitPane?.diffCount !== undefined ? { diffCount: userGitPane.diffCount } : {}),
     }
 
-    const sessionCatalog = loadSessionCatalog()
+    const projectCatalog = loadProjectCatalog()
     const mergedSnippets = mergeConfigSnippets(loadSnippetCatalog(), resolvedConfig.snippets)
     const initial = createInitialState(
       json.customCommands,
-      sessionCatalog,
+      projectCatalog,
       mergedSnippets,
-      sessionCatalog.length === 0,
+      projectCatalog.length === 0,
       {
         bars: json.bars,
         gitPane: gitPaneOverrides,
-        sessionBarVisible,
-        worktreeTemplates:
-          resolvedConfig.worktreeTemplates.length > 0
-            ? resolvedConfig.worktreeTemplates
-            : json.worktreeTemplates,
+        projectBarVisible,
       }
     )
     // Replace the module-level default with the fully-resolved initial state.
     // Preserves the dispatch baked into the store by app-store.ts.
     appStore.setState(initial)
-    const mostRecent = findMostRecentSession(sessionCatalog)
+    const mostRecent = findMostRecentProject(projectCatalog)
     if (mostRecent) {
       appStore.getState().dispatch({
-        sessionId: mostRecent.id,
-        type: 'load-session',
-        workspaceSnapshot: mostRecent.workspaceSnapshot,
+        projectId: mostRecent.id,
+        projectSnapshot: mostRecent.projectSnapshot,
+        type: 'load-project',
       })
     }
     return null
@@ -156,6 +166,15 @@ export function App({
   const state = useAppStore((s) => s)
   const dispatch = state.dispatch
 
+  // Config the settings screen can change under us. The resolved config file is
+  // the baseline each of these falls back to.
+  const autoCommitConfig = useAutoCommitConfig(resolvedConfig.autoCommit)
+  const aiUsageConfig = useAIUsageConfig(resolvedConfig.statusBar?.aiUsage)
+  const harmonizeClaudeTheme = useHarmonizeClaudeTheme(
+    resolvedConfig.theme?.beta?.harmonizeClaudeTheme
+  )
+  const snippetTriggerChar = useSnippetTriggerChar(resolvedConfig.snippetTriggerChar)
+
   useLayoutEffect(() => {
     setActiveDispatch(dispatch)
     return () => {
@@ -164,14 +183,26 @@ export function App({
     }
   }, [dispatch])
 
+  // Replays what the settings screen has written on top of the config file (the
+  // setters at the top of this component are its baseline). Deliberately after
+  // the effect above and never during render: a row applies its value through
+  // whatever owns it, and some of those owners are reached by dispatching.
+  // Layout effect, so it lands before the first paint.
+  useLayoutEffect(() => {
+    hydrateSettings(ALL_SETTING_ROWS, userConfig)
+    // Once per launch: the config file is read at startup and does not change
+    // under us, and every later write goes through `writeRow`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
   useEffect(() => {
-    if (!(resolvedConfig.theme?.beta?.harmonizeClaudeTheme === true)) return
+    if (!harmonizeClaudeTheme) return
     ensureClaudeSettingsThemePref()
     syncClaudeTheme(getCurrentTheme(), getCurrentMode())
     return subscribeThemeChanges((resolved, mode) => {
       syncClaudeTheme(resolved, mode)
     })
-  }, [resolvedConfig.theme?.beta?.harmonizeClaudeTheme])
+  }, [harmonizeClaudeTheme])
 
   useEffect(() => {
     // Opt-in via `integrations.claudeHooks` in aimux.config.ts. When enabled,
@@ -184,13 +215,12 @@ export function App({
   }, [resolvedConfig.integrations.claudeHooks])
 
   useEffect(() => {
-    const aiUsage = resolvedConfig.statusBar?.aiUsage
-    if (!(aiUsage?.enabled === true)) {
+    if (!(aiUsageConfig.enabled === true)) {
       aiUsageStore.getState().setEnabled(false)
       return
     }
     aiUsageStore.getState().setEnabled(true)
-    const handle = startAIUsageService(aiUsage, (snap) => {
+    const handle = startAIUsageService(aiUsageConfig, (snap) => {
       aiUsageStore.getState().setSnapshot(snap)
     })
     return () => {
@@ -198,7 +228,9 @@ export function App({
       aiUsageStore.getState().clear()
       aiUsageStore.getState().setEnabled(false)
     }
-  }, [resolvedConfig.statusBar?.aiUsage])
+    // Memoized by `useAIUsageConfig`, so toggling the indicator restarts the
+    // service and nothing else does.
+  }, [aiUsageConfig])
 
   useEffect(() => {
     if (process.env.AIMUX_DISABLE_UPDATE_CHECK === '1') return
@@ -228,16 +260,16 @@ export function App({
   }, [])
 
   useEffect(() => {
-    // One-shot cleanup: prune `aimux/` branches orphaned by temp worktrees that
+    // One-shot cleanup: prune `aimux/` branches orphaned by temp workspaces that
     // were deleted before delete-time branch cleanup existed. Gated by a config
     // flag so it runs once per machine. All git calls are best-effort (nothrow)
-    // and git protects branches still checked out in a live worktree.
+    // and git protects branches still checked out in a live workspace.
     if (loadConfig().prunedOrphanAimuxBranches === true) return
     void (async () => {
       const repoRoots = new Set<string>()
-      for (const session of loadSessionCatalog()) {
-        for (const worktree of session.worktrees ?? []) {
-          if (worktree.repoRoot !== '') repoRoots.add(worktree.repoRoot)
+      for (const project of loadProjectCatalog()) {
+        for (const workspace of project.workspaces ?? []) {
+          if (workspace.repoRoot !== '') repoRoots.add(workspace.repoRoot)
         }
       }
       let removed = 0
@@ -256,15 +288,15 @@ export function App({
   // still the bootstrap default, and useBackendRuntime's attach effect would
   // then hand 80x24 to the backend, resizing the daemon-persisted PTYs (or
   // newly-spawned ones) to the wrong size and stranding the assistant's
-  // already-drawn content in the top-left until a workspace switch.
+  // already-drawn content in the top-left until a project switch.
   const layoutRef = useRef(state.layout)
   const activeTab = useMemo(
     () => state.tabs.find((tab) => tab.id === state.activeTabId),
     [state.activeTabId, state.tabs]
   )
-  const currentSession = useMemo(
-    () => state.sessions.find((session) => session.id === state.currentSessionId),
-    [state.currentSessionId, state.sessions]
+  const currentProject = useMemo(
+    () => state.projects.find((project) => project.id === state.currentProjectId),
+    [state.currentProjectId, state.projects]
   )
   const activeMouseForwardingEnabled = activeTab?.terminalModes.mouseTrackingMode !== 'none'
   const activeLocalScrollbackEnabled =
@@ -285,11 +317,11 @@ export function App({
   snippetsRef.current = state.snippets
   const branchRef = useRef(state.gitPanel.branch)
   branchRef.current = state.gitPanel.branch
-  const triggerCharRef = useRef(resolvedConfig.snippetTriggerChar)
-  triggerCharRef.current = resolvedConfig.snippetTriggerChar
+  const triggerCharRef = useRef(snippetTriggerChar)
+  triggerCharRef.current = snippetTriggerChar
 
   const contentOriginRef = useRef<TerminalContentOrigin>({ cols: 0, rows: 0, x: 0, y: 0 })
-  const currentSessionWorkspaceSnapshot = currentSession?.workspaceSnapshot
+  const currentProjectProjectSnapshot = currentProject?.projectSnapshot
 
   // Must run before useBackendRuntime so its open-loop terminalSize seeds
   // layoutRef before the attach effect reads it. See the comment on layoutRef.
@@ -303,6 +335,15 @@ export function App({
   })
   layoutRef.current = { terminalCols: terminalSize.cols, terminalRows: terminalSize.rows }
 
+  // Reaches the setup widget, which hosts its own PTY outside root.tsx's pane
+  // tree and so never sees the onMeasure prop chain.
+  useLayoutEffect(() => {
+    setActiveMeasure(terminalSize.onMeasure)
+    return () => {
+      setActiveMeasure(null)
+    }
+  }, [terminalSize.onMeasure])
+
   const syntaxOverlayFlag = resolvedConfig.theme?.beta?.experimentalSyntaxHighlight === true
   const syntaxOverlayFlagRef = useRef(syntaxOverlayFlag)
   syntaxOverlayFlagRef.current = syntaxOverlayFlag
@@ -337,18 +378,20 @@ export function App({
   const { clearIdleTimer, clearStartupGrace, startStartupGrace } = useBackendRuntime({
     activeTabId: state.activeTabId,
     backend,
-    currentSessionId: state.currentSessionId,
-    currentSessionWorkspaceSnapshot,
+    currentProjectId: state.currentProjectId,
+    currentProjectProjectSnapshot,
     dispatch,
     layoutRef,
     resizingRef,
     syntaxOverlayEnabled,
   })
 
-  useWorkspaceAutosave(state, WORKSPACE_SAVE_DEBOUNCE_MS)
+  useProjectAutosave(state, PROJECT_SAVE_DEBOUNCE_MS)
   useDirectorySearch(state.modal, dispatch)
   useAutoCommitDriver({
-    config: resolvedConfig.autoCommit,
+    // Through the settings screen, so a change lands without a restart. The
+    // resolved config is the baseline it falls back to.
+    config: autoCommitConfig,
     dispatch,
     getProfileConfigRoot: getProfileConfigDir,
     state,
@@ -416,9 +459,9 @@ export function App({
     clearIdleTimer,
     clearStartupGrace,
     dispatch,
-    getCurrentSessionProjectPath: () => {
-      if (!(state.currentSessionId != null && state.currentSessionId !== '')) return
-      return getSessionProjectPath(state.sessions.find((s) => s.id === state.currentSessionId))
+    getCurrentProjectProjectPath: () => {
+      if (!(state.currentProjectId != null && state.currentProjectId !== '')) return
+      return getActiveWorkspacePath(state.projects.find((s) => s.id === state.currentProjectId))
     },
     // Read straight from the store, not stateRef. stateRef is only refreshed
     // on render, so within a single JS turn (a click handler that dispatches
@@ -432,6 +475,8 @@ export function App({
     themeId,
   }
 
+  useSetupRunner(state, sideEffectCtx)
+
   function processKeyResult(result: KeyResult, modeId: ModeId): void {
     for (const action of result.actions) {
       dispatch(action)
@@ -488,12 +533,12 @@ export function App({
       dispatch({ tabId: target.tabId, type: 'set-active-tab' })
       return
     }
-    if (target.kind === 'workspace' || target.kind === 'worktree') {
+    if (target.kind === 'project' || target.kind === 'workspace') {
       executeSideEffect(
         {
-          index: target.sessionIndex,
-          type: 'switch-session-by-index',
-          worktreeId: target.worktreeId,
+          index: target.projectIndex,
+          type: 'switch-project-by-index',
+          workspaceId: target.workspaceId,
         },
         sideEffectCtx
       )

package/src/cli/client/daemon-client.ts

@@ -205,10 +205,10 @@ export class DaemonClient {
     return response.payload
   }
 
-  async listTabs(sessionId: string): Promise<ListTabsResult> {
+  async listTabs(projectId: string): Promise<ListTabsResult> {
     const response = await this.send({
       id: crypto.randomUUID(),
-      payload: { sessionId },
+      payload: { projectId },
       type: 'listTabs',
     })
     if (response.type !== 'listTabsResult') {

package/src/cli/client/project-resolver.ts

@@ -0,0 +1,112 @@
+import type { ProjectRecord, WorkspaceRecord } from '../../state/types'
+
+import { findMostRecentProject, loadProjectCatalog } from '../../state/project-catalog'
+
+/**
+ * Where a command's target project 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 ProjectOrigin = 'flag' | 'env' | 'active'
+
+export interface ResolvedProject {
+  origin: ProjectOrigin
+  record: ProjectRecord
+}
+
+/** Env pin for headless orchestrators — `--project` still wins over it. */
+export const PROJECT_ENV_VAR = 'AIMUX_PROJECT'
+/** ponytail: pre-rename spelling, honoured for one release. Drop with --workspace. */
+const LEGACY_PROJECT_ENV_VAR = 'AIMUX_WORKSPACE'
+
+/** The project's primary (root) workspace, i.e. the repository it is about. */
+export function findPrimaryWorkspace(project: ProjectRecord): WorkspaceRecord | undefined {
+  return project.workspaces?.find((workspace) => workspace.source === 'primary')
+}
+
+/**
+ * The repo every fresh workspace for this project 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 workspace path hash.
+ */
+export function projectRepoRoot(project: ProjectRecord): string | null {
+  return findPrimaryWorkspace(project)?.repoRoot ?? project.projectPath ?? null
+}
+
+/** Stable project identity block embedded in command output. */
+export function projectIdentity(project: ProjectRecord): {
+  id: string
+  name: string
+  repoRoot: string | null
+} {
+  return { id: project.id, name: project.name, repoRoot: projectRepoRoot(project) }
+}
+
+/**
+ * Resolve `--project W` to a project record from the catalog, reporting where
+ * the choice came from. Precedence: the explicit flag, then `AIMUX_PROJECT`,
+ * then the most recently opened project. Throws when the catalog is empty (no
+ * project 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 resolveProjectWithOrigin(name: string | undefined): ResolvedProject {
+  const projects = loadProjectCatalog()
+  if (projects.length === 0) {
+    throw new Error(
+      'no projects found — create one from the aimux UI first (or pass --project once created)'
+    )
+  }
+
+  const flag = name !== undefined && name !== '' ? name : undefined
+  const env = process.env[PROJECT_ENV_VAR] ?? process.env[LEGACY_PROJECT_ENV_VAR]
+  const fromEnv = env != null && env !== '' ? env : undefined
+  const selector = flag ?? fromEnv
+  if (selector === undefined) {
+    const active = findMostRecentProject(projects)
+    if (!active) {
+      throw new Error('no active project and the catalog is empty')
+    }
+    return { origin: 'active', record: active }
+  }
+
+  return {
+    origin: flag !== undefined ? 'flag' : 'env',
+    record: matchProject(projects, selector),
+  }
+}
+
+export function resolveProject(name: string | undefined): ProjectRecord {
+  return resolveProjectWithOrigin(name).record
+}
+
+function matchProject(projects: ProjectRecord[], name: string): ProjectRecord {
+  const byId = projects.find((project) => project.id === name)
+  if (byId) return byId
+
+  const exactNameMatches = projects.filter((project) => project.name === name)
+  if (exactNameMatches.length > 1) {
+    throw new Error(
+      `project "${name}" matches multiple projects: ${exactNameMatches.map((s) => s.id).join(', ')}`
+    )
+  }
+  const exactOnly = exactNameMatches[0]
+  if (exactOnly) return exactOnly
+
+  const lower = name.toLowerCase()
+  const ciMatches = projects.filter((project) => project.name.toLowerCase() === lower)
+  if (ciMatches.length > 1) {
+    throw new Error(
+      `project "${name}" matches multiple projects: ${ciMatches.map((s) => s.id).join(', ')}`
+    )
+  }
+  const ciOnly = ciMatches[0]
+  if (ciOnly) return ciOnly
+
+  throw new Error(`project not found: ${name}`)
+}
+
+export function listProjects(): ProjectRecord[] {
+  return loadProjectCatalog()
+}

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

@@ -0,0 +1,32 @@
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_PROJECT_LIFECYCLE } from '../../../ipc/protocol'
+import { resolveProject } from '../../client/project-resolver'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const projectClose: CliCommand = {
+  args: [{ complete: { kind: 'dynamic', source: 'project' }, name: 'project', required: true }],
+  flags: SHARED_FLAGS,
+  group: 'project',
+  run: async (ctx) => {
+    const target = ctx.args.positionals[0]
+    if (typeof target !== 'string' || target.length === 0) {
+      throw new Error('target project is required (id or name)')
+    }
+    const project = resolveProject(target)
+
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_PROJECT_LIFECYCLE)) {
+      throw new Error(
+        'daemon predates projectLifecycle capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    await daemon.expectOk('closeProject', { targetProjectId: project.id })
+    writeJson({ closedProjectId: project.id, name: project.name })
+    return EXIT_OK
+  },
+  summary: 'Close a project (via the UI when attached, otherwise the catalog)',
+  verb: 'close',
+}

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

@@ -0,0 +1,93 @@
+import { resolve as resolvePath } from 'node:path'
+
+import type { CliCommand } from '../../registry'
+
+import { IPC_CAPABILITY_PROJECT_LIFECYCLE } from '../../../ipc/protocol'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, EXIT_TIMEOUT, writeJson } from '../../output'
+
+const DEFAULT_WAIT_TIMEOUT_MS = 30_000
+
+export const projectCreate: CliCommand = {
+  args: [{ complete: { kind: 'none' }, name: 'name', required: true }],
+  flags: [
+    ...SHARED_FLAGS,
+    {
+      complete: { kind: 'file' },
+      description: 'project path to associate with the project',
+      kind: 'string',
+      name: 'project',
+    },
+    {
+      description: 'immediately switch the running UI to the new project',
+      kind: 'boolean',
+      name: 'switch',
+    },
+    {
+      description: 'with --switch, wait until the UI confirms the switch completed',
+      kind: 'boolean',
+      name: 'wait',
+    },
+    {
+      description: 'timeout for --wait, in milliseconds (default 30000)',
+      kind: 'number',
+      name: 'timeout',
+    },
+  ],
+  group: 'project',
+  run: async (ctx) => {
+    const name = ctx.args.positionals[0]
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new Error('project 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)')
+    }
+
+    const daemon = await ctx.getDaemon()
+    if (!daemon.hasCapability(IPC_CAPABILITY_PROJECT_LIFECYCLE)) {
+      throw new Error(
+        'daemon predates projectLifecycle capability — restart aimux to pick up the new daemon'
+      )
+    }
+
+    if (!wait) {
+      await daemon.expectOk('createProject', { 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 `projectSwitched` once handleCreateProjectEffect has
+    // dispatched load-project. Match on name+projectPath since the CLI
+    // doesn't know the id the UI will assign to the new project.
+    const settled = new Promise<number>((resolve) => {
+      const off = daemon.on('projectSwitched', (payload) => {
+        off()
+        clearTimeout(timer)
+        writeJson({ name, projectId: payload.projectId, projectPath, switch: doSwitch })
+        resolve(EXIT_OK)
+      })
+      const timer = setTimeout(() => {
+        off()
+        writeJson({ error: 'timed out waiting for projectSwitched', name, projectPath })
+        resolve(EXIT_TIMEOUT)
+      }, timeoutMs)
+    })
+
+    await daemon.expectOk('createProject', { name, projectPath, switch: doSwitch })
+    return settled
+  },
+  summary: 'Create a new project (via the UI when attached, otherwise the catalog)',
+  verb: 'create',
+}

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

@@ -0,0 +1,25 @@
+import type { CliCommand } from '../../registry'
+
+import { listProjects } from '../../client/project-resolver'
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const projectList: CliCommand = {
+  args: [],
+  flags: SHARED_FLAGS,
+  group: 'project',
+  run: async () => {
+    const projects = listProjects()
+    writeJson({
+      projects: projects.map((project) => ({
+        id: project.id,
+        lastOpenedAt: project.lastOpenedAt,
+        name: project.name,
+        projectPath: project.projectPath,
+      })),
+    })
+    return EXIT_OK
+  },
+  summary: 'List known projects in the profile catalog',
+  verb: 'list',
+}

package/src/cli/commands/project/show.ts

@@ -0,0 +1,32 @@
+import type { CliCommand } from '../../registry'
+
+import { SHARED_FLAGS } from '../../flags'
+import { EXIT_OK, writeJson } from '../../output'
+
+export const projectShow: CliCommand = {
+  args: [],
+  flags: SHARED_FLAGS,
+  group: 'project',
+  run: async (ctx) => {
+    const project = ctx.getProject()
+    writeJson({
+      activeWorkspaceId: project.activeWorkspaceId,
+      createdAt: project.createdAt,
+      id: project.id,
+      lastOpenedAt: project.lastOpenedAt,
+      name: project.name,
+      projectPath: project.projectPath,
+      workspaces:
+        project.workspaces?.map((w) => ({
+          branch: w.branch,
+          id: w.id,
+          name: w.name,
+          path: w.path,
+          source: w.source,
+        })) ?? [],
+    })
+    return EXIT_OK
+  },
+  summary: 'Show the active project (or the one named via --project)',
+  verb: 'show',
+}