@brimveyn/aimux 1.20.4 → 1.22.0

package/src/git/pr-status.ts

@@ -0,0 +1,227 @@
+import { runCli } from '../services/ai-usage/spawn'
+
+export type PrCheckState = 'pass' | 'fail' | 'pending' | 'skipping' | 'cancel'
+
+export interface PrCheck {
+  name: string
+  workflow: string
+  state: PrCheckState
+  url: string
+  durationMs: number | null
+}
+
+export interface PrSummary {
+  number: number
+  title: string
+  body: string
+  state: string
+  isDraft: boolean
+  base: string
+  head: string
+  reviewDecision: string
+  /** MERGEABLE | CONFLICTING | UNKNOWN */
+  mergeable: string
+  /** CLEAN | BLOCKED | BEHIND | UNSTABLE | DIRTY | DRAFT | HAS_HOOKS | UNKNOWN */
+  mergeStateStatus: string
+  additions: number
+  deletions: number
+  changedFiles: number
+  url: string
+}
+
+export type PrStatusResult =
+  | { kind: 'ok'; pr: PrSummary; checks: PrCheck[] }
+  | { kind: 'no-pr' }
+  | { kind: 'no-gh' }
+  | { kind: 'error'; message: string }
+
+const PR_VIEW_FIELDS = [
+  'number',
+  'title',
+  'body',
+  'state',
+  'isDraft',
+  'url',
+  'baseRefName',
+  'headRefName',
+  'reviewDecision',
+  'mergeable',
+  'mergeStateStatus',
+  'additions',
+  'deletions',
+  'changedFiles',
+  'statusCheckRollup',
+].join(',')
+
+const NOT_AN_ERROR = [
+  'no pull requests found',
+  'no git remotes',
+  'not a git repository',
+  'none of the git remotes',
+  'no default remote',
+]
+
+function str(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+function num(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0
+}
+
+function duration(startedAt: unknown, completedAt: unknown): number | null {
+  const start = Date.parse(str(startedAt))
+  const end = Date.parse(str(completedAt))
+  if (Number.isNaN(start) || Number.isNaN(end) || end < start) return null
+  return end - start
+}
+
+// `gh` documents these buckets for `pr checks --json bucket`; we derive the same
+// classification from the raw rollup so a single `pr view` call covers both the
+// summary and the checks.
+function checkRunState(status: string, conclusion: string): PrCheckState {
+  if (status !== 'COMPLETED') return 'pending'
+  if (conclusion === 'SUCCESS' || conclusion === 'NEUTRAL') return 'pass'
+  if (conclusion === 'SKIPPED') return 'skipping'
+  if (conclusion === 'CANCELLED') return 'cancel'
+  return 'fail'
+}
+
+function statusContextState(state: string): PrCheckState {
+  if (state === 'SUCCESS') return 'pass'
+  if (state === 'PENDING' || state === 'EXPECTED') return 'pending'
+  return 'fail'
+}
+
+function toCheck(raw: unknown): PrCheck | null {
+  if (typeof raw !== 'object' || raw === null) return null
+  const entry = raw as Record<string, unknown>
+  if (entry.__typename === 'StatusContext') {
+    const name = str(entry.context)
+    if (name === '') return null
+    return {
+      durationMs: null,
+      name,
+      state: statusContextState(str(entry.state)),
+      url: str(entry.targetUrl),
+      workflow: '',
+    }
+  }
+  const name = str(entry.name)
+  if (name === '') return null
+  return {
+    durationMs: duration(entry.startedAt, entry.completedAt),
+    name,
+    state: checkRunState(str(entry.status), str(entry.conclusion)),
+    url: str(entry.detailsUrl),
+    workflow: str(entry.workflowName),
+  }
+}
+
+export function parsePrView(raw: unknown): PrStatusResult {
+  if (typeof raw !== 'object' || raw === null) return { kind: 'no-pr' }
+  const pr = raw as Record<string, unknown>
+  if (typeof pr.number !== 'number') return { kind: 'no-pr' }
+  const rollup = Array.isArray(pr.statusCheckRollup) ? pr.statusCheckRollup : []
+  return {
+    checks: rollup.map(toCheck).filter((c): c is PrCheck => c !== null),
+    kind: 'ok',
+    pr: {
+      additions: num(pr.additions),
+      base: str(pr.baseRefName),
+      body: str(pr.body).trim(),
+      changedFiles: num(pr.changedFiles),
+      deletions: num(pr.deletions),
+      head: str(pr.headRefName),
+      isDraft: pr.isDraft === true,
+      mergeable: str(pr.mergeable),
+      mergeStateStatus: str(pr.mergeStateStatus),
+      number: pr.number,
+      reviewDecision: str(pr.reviewDecision),
+      state: str(pr.state),
+      title: str(pr.title),
+      url: str(pr.url),
+    },
+  }
+}
+
+export type PrAction = 'merge' | null
+
+export interface PrActionState {
+  label: string
+  action: PrAction
+  tone: 'ok' | 'blocked' | 'neutral'
+}
+
+/**
+ * The headline GitHub puts on the merge box, and the one action worth wiring to
+ * it. Order matters: a terminal state beats everything, then a hard blocker
+ * (conflicts, draft), then whatever the checks are doing. Anything we can't
+ * offer an action for still gets an honest label rather than a dead button.
+ */
+export function prActionState(pr: PrSummary, checks: PrCheck[]): PrActionState {
+  if (pr.state === 'MERGED') return { action: null, label: 'Merged', tone: 'neutral' }
+  if (pr.state === 'CLOSED') return { action: null, label: 'Closed', tone: 'blocked' }
+  if (pr.isDraft) return { action: null, label: 'Draft', tone: 'neutral' }
+  if (pr.mergeable === 'CONFLICTING') {
+    return { action: null, label: 'Merge conflicts', tone: 'blocked' }
+  }
+  if (checks.some((c) => c.state === 'pending')) {
+    return { action: null, label: 'Checks running', tone: 'neutral' }
+  }
+  if (pr.mergeStateStatus === 'BLOCKED') return { action: null, label: 'Blocked', tone: 'blocked' }
+  if (pr.mergeStateStatus === 'BEHIND')
+    return { action: null, label: 'Out of date', tone: 'blocked' }
+  // UNSTABLE means a non-required check failed; GitHub still lets you merge.
+  if (pr.mergeStateStatus === 'UNSTABLE') {
+    return { action: 'merge', label: 'Checks failing', tone: 'blocked' }
+  }
+  if (pr.mergeStateStatus === 'CLEAN') {
+    return { action: 'merge', label: 'Ready to merge', tone: 'ok' }
+  }
+  return { action: null, label: 'Checking…', tone: 'neutral' }
+}
+
+export interface ClampedBody {
+  text: string
+  truncated: boolean
+}
+
+/**
+ * A PR body is a whole document; a bar widget gets a preview of it. Clamping on
+ * lines alone breaks on a wall-of-text paragraph and clamping on characters
+ * alone breaks on a bullet list, so whichever limit bites first wins.
+ */
+export function clampPrBody(body: string, maxLines = 5, maxChars = 260): ClampedBody {
+  const full = body.trimEnd()
+  const lines = full.split('\n')
+  let text = lines.slice(0, maxLines).join('\n')
+  if (text.length > maxChars) {
+    const space = text.lastIndexOf(' ', maxChars)
+    // Only respect a word boundary that isn't absurdly early, else hard-cut.
+    text = text.slice(0, space > maxChars / 2 ? space : maxChars)
+  }
+  text = text.trimEnd()
+  return { text, truncated: text.length < full.length }
+}
+
+export async function collectPrStatus(cwd: string): Promise<PrStatusResult> {
+  const gh = Bun.which('gh')
+  if (gh === null) return { kind: 'no-gh' }
+
+  const result = await runCli(gh, ['pr', 'view', '--json', PR_VIEW_FIELDS], 15_000, cwd)
+  if (!result.ok) {
+    // `gh` exits non-zero for every "there is simply nothing to show" case too:
+    // no PR on the branch, no GitHub remote, or a directory that isn't a repo
+    // at all (aimux projects can point anywhere). None of those is an error.
+    const stderr = result.stderr.toLowerCase()
+    if (NOT_AN_ERROR.some((needle) => stderr.includes(needle))) return { kind: 'no-pr' }
+    return { kind: 'error', message: (result.error ?? 'gh failed').slice(0, 200) }
+  }
+
+  try {
+    return parsePrView(JSON.parse(result.stdout))
+  } catch {
+    return { kind: 'no-pr' }
+  }
+}

package/src/git/repo-discovery.ts

@@ -79,7 +79,7 @@ const cache = new Map<string, CacheEntry>()
 /**
  * Cached variant. The cache key is `projectPath` + `maxDepth`: a depth change
  * invalidates the entry. The cache persists until `invalidateRepoCache()` or
- * process exit — discovery is one-shot per session per depth setting.
+ * process exit — discovery is one-shot per project per depth setting.
  */
 export async function discoverRepos(projectPath: string, maxDepth = 1): Promise<DiscoveredRepo[]> {
   const existing = cache.get(projectPath)

package/src/git/use-repo-discovery.ts

@@ -5,7 +5,7 @@ import { dispatchGlobal } from '../state/dispatch-ref'
 import { discoverRepos } from './repo-discovery'
 
 /**
- * Discover nested git repos inside `projectPath` once per session and push
+ * Discover nested git repos inside `projectPath` once per project and push
  * the result into state. No-op when the multi-repo config flag is off.
  */
 export function useRepoDiscovery(projectPath: string | undefined): void {

package/src/git/workspace-branch-poller.ts

@@ -0,0 +1,54 @@
+import { useEffect } from 'react'
+
+import { appStore } from '../state/app-store'
+import { dispatchGlobal } from '../state/dispatch-ref'
+import { getCurrentBranch } from '../ui/git-branch'
+
+const INTERVAL_MS = 4000
+
+// Single source of truth for "what git branch is each workspace on right now".
+// Polls every known workspace's path and dispatches update-workspace-record
+// when the live branch differs from the stored one. Components read
+// `workspace.branch` from state — no per-component polling, no flickers.
+//
+// Runs once when enabled; reads projects from the store on each tick so
+// project updates do NOT re-create the effect (which would otherwise feedback
+// off our own dispatches).
+export function useWorkspaceBranchPolling(enabled: boolean): void {
+  useEffect(() => {
+    if (!enabled) return
+
+    let cancelled = false
+    let timer: ReturnType<typeof setTimeout> | null = null
+
+    const tick = async () => {
+      const projects = appStore.getState().projects
+      await Promise.all(
+        projects.flatMap((project) =>
+          (project.workspaces ?? []).map(async (workspace) => {
+            if (workspace.path == null || workspace.path === '') return
+            const branch = await getCurrentBranch(workspace.path)
+            if (cancelled) return
+            if (branch != null && branch !== workspace.branch) {
+              dispatchGlobal({
+                patch: { branch },
+                projectId: project.id,
+                type: 'update-workspace-record',
+                workspaceId: workspace.id,
+              })
+            }
+          })
+        )
+      )
+      if (cancelled) return
+      timer = setTimeout(() => void tick(), INTERVAL_MS)
+    }
+
+    void tick()
+
+    return () => {
+      cancelled = true
+      if (timer != null) clearTimeout(timer)
+    }
+  }, [enabled])
+}

package/src/git/workspace-divergence-poller.ts

@@ -0,0 +1,65 @@
+import { useEffect } from 'react'
+
+import type { BranchDivergence } from '../state/types'
+
+import { useAppStore } from '../state/app-store'
+import { dispatchGlobal } from '../state/dispatch-ref'
+import { getBranchDivergence, getWorkspaceDiffStat } from './divergence'
+
+const INTERVAL_MS = 4000
+
+// Polls per-workspace base divergence for the current project while enabled and
+// dispatches it into workspaceDivergence. Only workspaces that record a baseRef
+// (the aimux-created ones) are measured; the primary and externally-discovered
+// workspaces have no recorded base and are left out.
+export function useWorkspaceDivergencePolling(enabled: boolean): void {
+  const currentProjectId = useAppStore((s) => s.currentProjectId)
+  const projects = useAppStore((s) => s.projects)
+
+  useEffect(() => {
+    if (!enabled) return
+    const project =
+      currentProjectId != null && currentProjectId !== ''
+        ? projects.find((s) => s.id === currentProjectId)
+        : undefined
+    const targets = (project?.workspaces ?? []).filter(
+      (w) => w.baseRef != null && w.baseRef !== '' && w.branch != null && w.branch !== ''
+    )
+    if (targets.length === 0) return
+
+    let cancelled = false
+    let timer: ReturnType<typeof setTimeout> | null = null
+
+    const tick = async () => {
+      const entries = await Promise.all(
+        targets.map(async (workspace) => {
+          const base = workspace.baseRef
+          const branch = workspace.branch
+          if (base == null || branch == null) return null
+          // Commits come from the repo root (comparing two refs); lines come
+          // from the workspace itself, so uncommitted work is counted too.
+          const [divergence, stat] = await Promise.all([
+            getBranchDivergence(workspace.repoRoot, base, branch),
+            getWorkspaceDiffStat(workspace.path, base),
+          ])
+          if (divergence == null) return null
+          return [workspace.id, { ...divergence, ...stat }] as const
+        })
+      )
+      if (cancelled) return
+      const next: Record<string, BranchDivergence> = {}
+      for (const entry of entries) {
+        if (entry != null) next[entry[0]] = entry[1]
+      }
+      dispatchGlobal({ divergence: next, type: 'set-workspace-divergence' })
+      timer = setTimeout(() => void tick(), INTERVAL_MS)
+    }
+
+    void tick()
+
+    return () => {
+      cancelled = true
+      if (timer != null) clearTimeout(timer)
+    }
+  }, [enabled, currentProjectId, projects])
+}

package/src/git/worktree.ts

@@ -69,6 +69,35 @@ export async function resolveGitRef(repoPath: string, ref: string): Promise<stri
   return result.text().trim() || undefined
 }
 
+// The branch a new workspace forks from unless the user picks another base.
+// `origin/HEAD` is the only authoritative answer; it is missing on repos cloned
+// with --no-checkout or created locally, hence the name probes behind it.
+export async function getDefaultBranch(repoPath: string): Promise<string | undefined> {
+  const head = await $`git -C ${repoPath} symbolic-ref --short refs/remotes/origin/HEAD`
+    .quiet()
+    .nothrow()
+  if (head.exitCode === 0) {
+    const ref = head.text().trim()
+    const short = ref.startsWith('origin/') ? ref.slice('origin/'.length) : ref
+    if (short !== '') return short
+  }
+  const locals = await listLocalBranches(repoPath)
+  return ['main', 'master'].find((name) => locals.includes(name))
+}
+
+// Rename a local branch. Returns false (without throwing) when git refuses —
+// the target name already exists, most likely — so a failed rename leaves the
+// workspace on the branch it was created with instead of losing it.
+export async function renameGitBranch(
+  repoPath: string,
+  from: string,
+  to: string
+): Promise<boolean> {
+  if (from === '' || to === '' || from === to) return false
+  const result = await $`git -C ${repoPath} branch -m ${from} ${to}`.quiet().nothrow()
+  return result.exitCode === 0
+}
+
 export async function createGitWorktree({
   baseRef,
   branchName,

package/src/index.tsx

@@ -5,7 +5,7 @@
 const command = process.argv[2]
 
 // Shell completion. First branch and cheapest: it loads the CLI registry and
-// nothing else — no daemon client, no session backend, no renderer.
+// nothing else — no daemon client, no project backend, no renderer.
 if (command === '__complete') {
   const { runComplete } = await import('./cli/completion/entry')
   process.exit(await runComplete(process.argv.slice(3)))
@@ -19,7 +19,7 @@ if (command === 'completion') {
 // CLI control plane (docs/reference/cli.md). Branch BEFORE the UI bootstrap so
 // `aimux tab list` from a non-TTY shell never spins up the React renderer.
 // Dynamic import keeps the CLI code out of the UI's cold-start cost.
-const CLI_GROUPS = new Set(['tab', 'workspace', 'worktree', 'worker'])
+const CLI_GROUPS = new Set(['tab', 'project', 'workspace', 'worker'])
 if (typeof command === 'string' && CLI_GROUPS.has(command)) {
   const { runCli } = await import('./cli')
   process.exit(await runCli(process.argv.slice(2)))
@@ -72,8 +72,14 @@ if (command === '--help' || command === '-h' || command === 'help') {
   process.exit(await runCli([]))
 }
 
+// Sequential ON PURPOSE: @opentui/react evaluates @opentui/core as part of its
+// own module graph. Loading both concurrently races the two evaluations and
+// react's chunk can hit `class X extends TextNodeRenderable` while core is
+// still initializing (ReferenceError: cannot access before initialization).
+// react has to wait on core either way, so this costs nothing.
+const { createCliRenderer } = await import('@opentui/core')
+
 const [
-  { createCliRenderer },
   { createRoot },
   { App },
   { loadUserConfig },
@@ -82,7 +88,6 @@ const [
   { createSessionBackend },
   { maybeAutoInstallCompletion },
 ] = await Promise.all([
-  import('@opentui/core'),
   import('@opentui/react'),
   import('./app'),
   import('./config/loader'),
@@ -91,7 +96,7 @@ const [
   import('./session-backend/bootstrap'),
   import('./cli/completion/install'),
 ])
-const resolvedConfig = await loadUserConfig()
+const { resolved: resolvedConfig, user: userConfig } = await loadUserConfig()
 
 // First launch (and after every upgrade): drop the shell completion script in
 // the conventional location for $SHELL. Silent and best-effort — it writes one
@@ -149,4 +154,4 @@ const backend = await createSessionBackend({
 })
 logDebug('index.backendReady', { backend: backend.constructor.name, runtimeProfile })
 
-root.render(<App backend={backend} resolvedConfig={resolvedConfig} />)
+root.render(<App backend={backend} resolvedConfig={resolvedConfig} userConfig={userConfig} />)

package/src/input/keymap/help-entries.ts

@@ -11,15 +11,17 @@ export const HELP_MODE_LABELS: { modeId: ModeId; label: string }[] = [
   { label: 'Navigation', modeId: 'navigation' },
   { label: 'Terminal input', modeId: 'terminal-input' },
   { label: 'Git mode', modeId: 'git-mode' },
+  { label: 'Settings', modeId: 'settings' },
   { label: 'Git commit', modeId: 'modal.git-commit' },
   { label: 'New tab', modeId: 'modal.new-tab.command-edit' },
   { label: 'New tab — command', modeId: 'modal.new-tab.command-edit' },
-  { label: 'Workspace picker', modeId: 'modal.session-picker.filtering' },
-  { label: 'Workspace picker — filter', modeId: 'modal.session-picker.filtering' },
-  { label: 'Workspace name', modeId: 'modal.session-name' },
-  { label: 'Create workspace', modeId: 'modal.create-session' },
+  { label: 'Project picker', modeId: 'modal.project-picker.filtering' },
+  { label: 'Project picker — filter', modeId: 'modal.project-picker.filtering' },
+  { label: 'Project name', modeId: 'modal.project-name' },
+  { label: 'Create project', modeId: 'modal.create-project' },
+  { label: 'Create workspace', modeId: 'modal.create-workspace' },
   { label: 'Rename tab', modeId: 'modal.rename-tab' },
-  { label: 'Rename worktree', modeId: 'modal.rename-worktree' },
+  { label: 'Rename workspace', modeId: 'modal.rename-workspace' },
   { label: 'Snippet picker', modeId: 'modal.snippet-picker.filtering' },
   { label: 'Snippet picker — filter', modeId: 'modal.snippet-picker.filtering' },
   { label: 'Snippet editor', modeId: 'modal.snippet-editor' },

package/src/input/modes/bridge.ts

@@ -6,18 +6,22 @@ type SupportedModalType = Exclude<ModalType, null>
 const DIRECT_FOCUS_MODE_IDS: Partial<Record<FocusMode, ModeId>> = {
   'git': 'git-mode',
   'navigation': 'navigation',
+  'settings': 'settings',
   'terminal-input': 'terminal-input',
 }
 
 const COMMAND_EDIT_MODE_IDS: Partial<Record<SupportedModalType, ModeId>> = {
-  'create-session': 'modal.create-session',
+  'create-project': 'modal.create-project',
+  'create-workspace': 'modal.create-workspace',
   'git-commit': 'modal.git-commit',
   'help': 'modal.help.filtering',
   'new-tab': 'modal.new-tab.command-edit',
+  'project-name': 'modal.project-name',
+  'project-picker': 'modal.project-picker.filtering',
   'rename-tab': 'modal.rename-tab',
-  'rename-worktree': 'modal.rename-worktree',
-  'session-name': 'modal.session-name',
-  'session-picker': 'modal.session-picker.filtering',
+  'rename-workspace': 'modal.rename-workspace',
+  'setting-text': 'modal.setting-text',
+  'settings-search': 'modal.settings-search.filtering',
   'snippet-editor': 'modal.snippet-editor',
   'snippet-picker': 'modal.snippet-picker.filtering',
   'split-picker': 'modal.split-picker',
@@ -27,9 +31,9 @@ const COMMAND_EDIT_MODE_IDS: Partial<Record<SupportedModalType, ModeId>> = {
 const MODAL_MODE_IDS: Partial<Record<SupportedModalType, ModeId>> = {
   'ai-usage': 'modal.ai-usage',
   'update-available': 'modal.update-available',
-  'worktree-delete-confirm': 'modal.worktree-delete-confirm',
-  'worktree-move': 'modal.worktree-move',
-  'worktree-move-confirm': 'modal.worktree-move-confirm',
+  'workspace-delete-confirm': 'modal.workspace-delete-confirm',
+  'workspace-move': 'modal.workspace-move',
+  'workspace-move-confirm': 'modal.workspace-move-confirm',
 }
 
 export function deriveModeId(state: AppState): ModeId {
@@ -41,8 +45,8 @@ export function deriveModeId(state: AppState): ModeId {
 
   // Overlay on top of git mode without flipping focusMode (like help) — route
   // input to the picker while it's open even though focus stays 'git'.
-  if (state.modal.type === 'worktree-move') {
-    return 'modal.worktree-move'
+  if (state.modal.type === 'workspace-move') {
+    return 'modal.workspace-move'
   }
 
   // Flash-jump overlay: same pattern — renders on top of navigation, all
@@ -60,9 +64,6 @@ export function deriveModeId(state: AppState): ModeId {
     if (state.modal.type === 'new-tab' && state.modal.editingCommand !== null) {
       return 'modal.new-tab.editing-command'
     }
-    if (state.modal.type === 'new-tab' && state.modal.worktreeDeletePrompt !== null) {
-      return 'modal.new-tab.worktree-delete-confirm'
-    }
     if (state.modal.type === 'git-commit' && state.modal.stage === 'confirm') {
       return 'modal.git-commit.confirm'
     }

package/src/input/modes/handlers/shared.ts

@@ -1,4 +1,4 @@
-import type { AppAction } from '../../../state/types'
+import type { AppAction } from '../../../state/actions'
 import type { KeyInput, KeyResult, ModeId, SideEffect } from '../types'
 
 type SelectionDelta = -1 | 1

package/src/input/modes/transitions.ts

@@ -1,51 +1,64 @@
 import type { ModeId } from './types'
 
 const TRANSITIONS: Record<ModeId, readonly ModeId[]> = {
-  'git-mode': ['navigation', 'modal.git-commit', 'modal.worktree-move'],
+  'git-mode': ['navigation', 'modal.git-commit', 'modal.workspace-move'],
   'modal.ai-usage': ['navigation', 'terminal-input'],
-  'modal.create-session': ['navigation', 'modal.session-picker.filtering'],
+  'modal.create-project': ['navigation', 'modal.project-picker.filtering'],
+  'modal.create-workspace': ['navigation', 'terminal-input'],
   'modal.flash-jump': ['navigation'],
   'modal.git-commit': ['git-mode', 'modal.git-commit.confirm', 'modal.git-commit.generating'],
   'modal.git-commit.confirm': ['modal.git-commit', 'git-mode'],
   'modal.git-commit.generating': ['modal.git-commit', 'modal.git-commit.confirm', 'git-mode'],
   'modal.help.filtering': ['navigation'],
-  'modal.new-tab.command-edit': [
-    'navigation',
-    'modal.new-tab.editing-command',
-    'modal.new-tab.worktree-delete-confirm',
-  ],
+  'modal.new-tab.command-edit': ['navigation', 'modal.new-tab.editing-command'],
   'modal.new-tab.editing-command': ['navigation', 'modal.new-tab.command-edit'],
-  'modal.new-tab.worktree-delete-confirm': ['navigation', 'modal.new-tab.command-edit'],
+  'modal.project-name': ['modal.project-picker.filtering', 'navigation'],
+  'modal.project-picker.filtering': ['navigation', 'modal.project-name', 'modal.create-project'],
   'modal.rename-tab': ['navigation'],
-  'modal.rename-worktree': ['navigation'],
-  'modal.session-name': ['modal.session-picker.filtering', 'navigation'],
-  'modal.session-picker.filtering': ['navigation', 'modal.session-name', 'modal.create-session'],
+  'modal.rename-workspace': ['navigation'],
+  'modal.setting-text': ['settings'],
+  'modal.settings-search.filtering': ['settings'],
   'modal.snippet-editor': ['navigation', 'modal.snippet-picker.filtering'],
-  'modal.snippet-picker.filtering': ['navigation', 'modal.snippet-editor'],
+  // Both pickers are reachable from the settings screen as well as from the
+  // panes, and `returnTo` sends each one back where it came from.
+  'modal.snippet-picker.filtering': ['navigation', 'settings', 'modal.snippet-editor'],
   'modal.split-picker': ['navigation', 'terminal-input'],
-  'modal.theme-picker.filtering': ['navigation'],
+  'modal.theme-picker.filtering': ['navigation', 'settings'],
   'modal.update-available': ['navigation'],
-  'modal.worktree-delete-confirm': ['navigation'],
-  'modal.worktree-move': ['git-mode', 'navigation'],
-  'modal.worktree-move-confirm': ['navigation'],
+  'modal.workspace-delete-confirm': ['navigation'],
+  'modal.workspace-move': ['git-mode', 'navigation'],
+  'modal.workspace-move-confirm': ['navigation'],
   'navigation': [
     'terminal-input',
+    'modal.create-workspace',
     'modal.new-tab.command-edit',
     'modal.new-tab.editing-command',
-    'modal.session-picker.filtering',
+    'modal.project-picker.filtering',
     'modal.help.filtering',
     'modal.snippet-picker.filtering',
     'modal.theme-picker.filtering',
     'modal.rename-tab',
-    'modal.rename-worktree',
+    'modal.rename-workspace',
     'modal.update-available',
     'modal.ai-usage',
-    'modal.worktree-delete-confirm',
-    'modal.worktree-move-confirm',
+    'modal.workspace-delete-confirm',
+    'modal.workspace-move-confirm',
     'modal.flash-jump',
     'git-mode',
+    'settings',
+  ],
+  // The help overlay opens over settings without a transition (it leaves
+  // focusMode alone). The two pickers an action row hands over to are dispatched
+  // directly rather than through a KeyResult, but they are listed because that is
+  // what this table is for: saying where a mode can go.
+  'settings': [
+    'navigation',
+    'modal.setting-text',
+    'modal.settings-search.filtering',
+    'modal.theme-picker.filtering',
+    'modal.snippet-picker.filtering',
   ],
-  'terminal-input': ['navigation', 'modal.split-picker', 'modal.ai-usage'],
+  'terminal-input': ['navigation', 'modal.split-picker', 'modal.ai-usage', 'settings'],
 }
 
 export function isValidTransition(from: ModeId, to: ModeId): boolean {