@brimveyn/aimux-config 0.10.9 → 0.11.0

package/src/app-types.ts

@@ -0,0 +1,1467 @@
+// -----------------------------------------------------------------------------
+// The aimux application state, mode and layout shapes.
+//
+// These are the SOURCE definitions, not a copy. They live in this package
+// because everything a user's `aimux.config.ts` or a plugin can touch has to
+// be importable without depending on the aimux binary — and because the
+// previous arrangement, two hand-maintained copies "kept structurally
+// identical", had already drifted on six types by the time anyone checked.
+//
+// `src/state/types.ts` re-exports from here.
+// -----------------------------------------------------------------------------
+
+import type { LayoutNode, SnippetVar, SplitDirection } from './types'
+
+export type BuiltinAssistantId =
+  | 'claude'
+  | 'codex'
+  | 'opencode'
+  | 'grok'
+  | 'kimi'
+  | 'terminal'
+  | 'antigravity'
+
+export type AssistantId = BuiltinAssistantId | (string & {})
+
+export type TabStatus = 'starting' | 'running' | 'disconnected' | 'error'
+
+/**
+ * Status values that may appear in legacy on-disk project snapshots but are
+ * not produced by the running app anymore. Filtered at restore time.
+ */
+export type LegacyPersistedTabStatus = TabStatus | 'exited'
+
+export type TabActivity = 'working' | 'waiting-input' | 'idle'
+
+/**
+ * Classifies why a tab is blocked on user input. `permission` is a tool /
+ * command approval prompt; `question` is any other prompt the assistant is
+ * waiting on. Carried by the `tabQuestion` server event so an orchestrator can
+ * branch without re-scraping the screen.
+ */
+export type QuestionKind = 'question' | 'permission'
+
+/**
+ * Per-project status flags. Both can be true at once (e.g. one tab working,
+ * another waiting for user input) so we keep them as independent booleans
+ * rather than a single priority enum.
+ */
+export interface ProjectStatus {
+  working: boolean
+  waiting: boolean
+}
+
+/**
+ * A workspace's status, as the sidebar draws it. `working`/`waiting` mirror
+ * `ProjectStatus` one level down; `done` is a latch — an assistant here
+ * finished a turn and nobody has looked yet — cleared when the workspace is
+ * entered or when it goes back to work.
+ */
+export interface WorkspaceActivity {
+  working: boolean
+  waiting: boolean
+  done: boolean
+}
+
+export type FocusMode =
+  | 'navigation'
+  | 'terminal-input'
+  | 'modal'
+  | 'command-edit'
+  | 'git'
+  | 'settings'
+  | 'stats'
+  /**
+   * A plugin's full-screen view has replaced the pane tree. Which one is in
+   * `AppState.activePluginView` — one focus mode covers every plugin view, the
+   * way `modal` covers every modal, so adding a view is a registration rather
+   * than a change to this union.
+   */
+  | 'plugin-view'
+
+export type ModalType =
+  | 'new-tab'
+  | 'project-picker'
+  | 'project-name'
+  | 'create-project'
+  | 'create-workspace'
+  | 'rename-tab'
+  | 'rename-workspace'
+  | 'snippet-picker'
+  | 'snippet-editor'
+  | 'theme-picker'
+  | 'help'
+  | 'split-picker'
+  | 'git-commit'
+  | 'update-available'
+  | 'quotas'
+  | 'workspace-move'
+  | 'workspace-move-confirm'
+  | 'workspace-delete-confirm'
+  | 'flash-jump'
+  | 'setting-text'
+  | 'settings-search'
+  /**
+   * Every plugin modal, the way `plugin-view` covers every plugin view. Which
+   * one is on `ModalPlugin.modalId`, so adding a modal is a registration
+   * rather than an arm on this union.
+   */
+  | 'plugin-modal'
+  | null
+
+export interface TerminalSpan {
+  text: string
+  /** Hex color for RGB cells, or undefined for the "default" foreground. */
+  fg?: string
+  /** Hex color for RGB cells, or undefined for the "default" background. */
+  bg?: string
+  /** ANSI palette index (0-255) when the cell emitted an indexed color.
+   *  Resolved client-side against the host terminal's queried palette so
+   *  user themes (Ghostty, iTerm2, …) show through. Wins over `fg` if set. */
+  fgPalette?: number
+  /** ANSI palette index (0-255). Resolved client-side. Wins over `bg`. */
+  bgPalette?: number
+  bold?: boolean
+  italic?: boolean
+  underline?: boolean
+  cursor?: boolean
+}
+
+export interface TerminalLine {
+  spans: TerminalSpan[]
+}
+
+/** DECSCUSR cursor shape; 'default' restores the host terminal's configured cursor. */
+export type TerminalCursorStyle = 'block' | 'underline' | 'bar' | 'default'
+
+export interface TerminalSnapshot {
+  lines: TerminalLine[]
+  tailLines?: TerminalLine[]
+  viewportY: number
+  baseY: number
+  cursorVisible: boolean
+  cursorStyle?: TerminalCursorStyle
+  /** Blink flag from DECSCUSR; undefined means "host terminal's default". */
+  cursorBlink?: boolean
+  /** Cursor row relative to the rendered viewport; outside [0, rows) when
+   *  the user scrolled the viewport away from the active screen. */
+  cursorRow?: number
+  cursorCol?: number
+}
+
+// The scroll position is owned end-to-end by the backend emulator; this type
+// only describes the re-anchor target the backend computes for itself across a
+// reflow. The frontend no longer derives, stores, or sends a scroll intent.
+export type ScrollIntent = { kind: 'bottom' } | { absoluteLine: number; kind: 'anchor' }
+
+export interface TerminalModeState {
+  mouseTrackingMode: 'none' | 'x10' | 'vt200' | 'drag' | 'any'
+  sendFocusMode: boolean
+  alternateScrollMode: boolean
+  isAlternateBuffer: boolean
+  bracketedPasteMode: boolean
+}
+
+export interface PersistedTabSnapshot {
+  id: string
+  assistant: AssistantId
+  title: string
+  command: string
+  /** Optional and additive: an older build ignores it and spawns fresh. */
+  sessionId?: string
+  status: Exclude<LegacyPersistedTabStatus, 'disconnected'>
+  buffer: string
+  viewport?: TerminalSnapshot
+  terminalModes: TerminalModeState
+  errorMessage?: string
+  exitCode?: number
+  workspaceId?: string
+  /** Stable project-scoped name assigned by the headless worker facade. */
+  workerName?: string
+  autoRenameStatus?: 'eligible' | 'attempted'
+}
+
+export interface ProjectSnapshotV1 {
+  version: 1
+  savedAt: string
+  activeTabId: string | null
+  sidebar: {
+    visible: boolean
+    width: number
+  }
+  tabs: PersistedTabSnapshot[]
+  layoutTree?: LayoutNode
+  layoutTrees?: Record<string, LayoutNode>
+  tabGroupMap?: Record<string, string>
+  /**
+   * Last viewed tab per workspace, keyed by workspace id. Optional and additive
+   * (no version bump): older builds ignore it, newer builds tolerate its
+   * absence. Written now so the data accrues, but restoring it at startup is
+   * gated off until a future change flips RESTORE_LAST_ACTIVE_TAB_BY_WORKSPACE.
+   */
+  lastActiveTabByWorkspace?: Record<string, string>
+}
+
+export type WorkspaceSource = 'primary' | 'aimux-temp' | 'external'
+
+export interface WorkspaceRecord {
+  id: string
+  name: string
+  path: string
+  repoRoot: string
+  branch?: string
+  baseRef?: string
+  commitSha?: string
+  source: WorkspaceSource
+  createdByAimux: boolean
+  color?: string
+  createdAt: string
+  updatedAt: string
+  /** Last setup-script run for this workspace. Display only — the auto-run gate
+   *  is "this session has not seen this workspace id before". */
+  setupRanAt?: string
+  setupExitCode?: number
+}
+
+export interface ProjectRecord {
+  id: string
+  name: string
+  projectPath?: string
+  createdAt: string
+  updatedAt: string
+  lastOpenedAt: string
+  order?: number
+  projectSnapshot?: ProjectSnapshotV1
+  workspaces?: WorkspaceRecord[]
+  activeWorkspaceId?: string
+  /**
+   * The branch new workspaces fork from, when the repo's own default is the
+   * wrong answer — a gitflow repo branches off `develop` while still declaring
+   * `main` as its default, and nothing about the repo says so. Per project
+   * because the convention is the team's, not the user's: three repos, three
+   * answers. Unset means the repo's default branch.
+   */
+  defaultBaseRef?: string
+  /**
+   * Folded in the sidebar: the project's workspace rows are hidden, bar the one
+   * the cursor is on. Persisted, because a fold you have to redo on every start
+   * is worse than no fold at all.
+   */
+  collapsed?: boolean
+}
+
+export interface ProjectBarState {
+  visible: boolean
+}
+
+export interface TabSession {
+  id: string
+  assistant: AssistantId
+  title: string
+  status: TabStatus
+  activity?: TabActivity
+  buffer: string
+  viewport?: TerminalSnapshot
+  terminalModes: TerminalModeState
+  command: string
+  /**
+   * Names the assistant conversation this tab owns, so a respawn reopens it
+   * instead of starting over. Minted when the tab is created and handed to the
+   * CLI at spawn — we pick the id rather than discover it afterwards, because
+   * discovery cannot tell two tabs sharing a cwd apart.
+   *
+   * Absent on tabs created before this existed, and on assistants with no
+   * session support; both spawn exactly as they always did.
+   */
+  sessionId?: string
+  /**
+   * Deliberately put to sleep: the PTY is gone, the frozen viewport stays, and
+   * focusing the tab resumes it. Distinct from the `disconnected` it rides on —
+   * that also means "restored from a snapshot after a restart" — and only used
+   * to tell the two apart in the sidebar glyph, the pane overlay, and the wake.
+   * Ephemeral — never persisted, never on the wire: a restart turns every tab
+   * disconnected anyway, and Ctrl+r resumes them just the same.
+   */
+  hibernated?: boolean
+  errorMessage?: string
+  exitCode?: number
+  workspaceId?: string
+  /**
+   * This tab is the one that rang: it finished a turn while you were looking
+   * elsewhere. Set alongside the workspace's own tick and cleared the moment
+   * the tab is opened or goes back to work, so the notification points at
+   * something rather than just happening. Ephemeral — never persisted, never
+   * on the wire.
+   */
+  unseen?: boolean
+  /** Stable project-scoped name assigned by the headless worker facade. */
+  workerName?: string
+  autoRenameStatus?: 'eligible' | 'attempted'
+  /**
+   * A real PTY tab that no chrome enumerates: absent from the top tab bar, from
+   * tab navigation, from `activeTabId` picks, and from the persisted snapshot.
+   * Rendered by whatever created it — today only the setup widget.
+   * `filterTabsForActiveWorkspace` is the single guard the UI paths share.
+   */
+  hidden?: boolean
+  /**
+   * Who owns this tab. Separate from `hidden` on purpose: promoting a setup tab
+   * into the main pane clears `hidden` but must not turn it back into an
+   * ordinary tab, or the PTY exit would close it and take the failure output
+   * with it — which is the one thing the promotion exists to read.
+   *
+   * ponytail: not on the ipc wire nor in the snapshot, so a promoted setup tab
+   * comes back from a restart as a plain tab running `bash …/setup.sh`. Add it
+   * to `TabSessionSummary` if that ever matters.
+   */
+  role?: 'setup'
+}
+
+export type BarSide = 'left' | 'right'
+
+/**
+ * One widget slot in a bar. `grow` is the flex weight opentui consumes
+ * directly; hidden widgets keep their weight but are excluded from the layout.
+ */
+export interface BarWidget {
+  id: string
+  grow: number
+  visible: boolean
+  /**
+   * Set when a plugin's manifest asked for this placement rather than the
+   * user. It is what lets an unload withdraw what the plugin put there without
+   * touching what the user arranged — and the moment the user moves or hides
+   * the widget the mark is dropped, because the placement has become theirs.
+   */
+  placedBy?: 'plugin'
+}
+
+export interface BarState {
+  visible: boolean
+  width: number
+  /** Ordered top → bottom. */
+  widgets: BarWidget[]
+}
+
+export type BarsState = Record<BarSide, BarState>
+
+export type GitPanePathConfig =
+  | { enabled: false }
+  | { enabled: true; pathFn?: (path: string) => string }
+
+export interface GitPaneDiffCountConfig {
+  enabled: boolean
+}
+
+export interface GitPaneState {
+  diffModeRatio: number
+  fileListMode: GitFileListMode
+  treeCompaction: boolean
+  path: GitPanePathConfig
+  diffCount: GitPaneDiffCountConfig
+  /** Prefetch this many neighbours around the selection. 0 disables prefetch. */
+  prefetchRadius: number
+}
+
+export type GitFileStatus = 'M' | 'A' | 'D' | 'R' | 'C' | 'U' | '?'
+
+export type GitFileSection = 'staged' | 'unstaged' | 'untracked' | 'historical'
+
+export interface GitFileEntry {
+  path: string
+  renamedFrom?: string
+  section: GitFileSection
+  status: GitFileStatus
+  added: number | null
+  removed: number | null
+  /** Absolute path to the originating git repo. Set when the entry comes from a sub-repo. */
+  repoPath?: string
+}
+
+export type GitPanelError = 'not-a-repo' | 'unknown'
+
+export interface GitPanelState {
+  branch: string | null
+  ahead: number
+  behind: number
+  files: GitFileEntry[]
+  error: GitPanelError | null
+}
+
+export type DiffFileStatus =
+  | 'modified'
+  | 'new'
+  | 'deleted'
+  | 'binary'
+  | 'renamed'
+  | 'image'
+  | 'too-large'
+
+export interface DiffData {
+  path: string
+  status: DiffFileStatus
+  oldPath?: string
+  rawDiff: string
+  binarySizeBefore?: number
+  binarySizeAfter?: number
+  errorMessage?: string
+  imageBytesBefore?: Uint8Array
+  imageBytesAfter?: Uint8Array
+  imageMime?: string
+  imageFormatLabel?: string
+}
+
+export type GitDiffView = 'split' | 'stacked'
+export type GitFileListMode = 'tree' | 'flat'
+
+export interface FoldState {
+  top: number
+  bottom: number
+}
+
+export interface ParsedDiffEntry {
+  hash: string
+  // Stored as unknown at the state boundary and narrowed at read sites.
+  file: unknown
+}
+
+export interface HighlightsEntry {
+  hash: string
+  themeId: string
+  // See ParsedDiffEntry note — narrowed via getHighlights().
+  add: unknown
+  del: unknown
+}
+
+export interface GitModeState {
+  selectedEntryKey: string | null
+  collapsedFolders: Record<string, true>
+  diffs: Record<string, DiffData>
+  /** Parsed diff keyed by fileKey. Invalidated on file change or head offset shift. */
+  parsedFiles: Record<string, ParsedDiffEntry>
+  /** Tokenised highlights keyed by `${fileKey}|${themeId}`. */
+  highlights: Record<string, HighlightsEntry>
+  loading: Record<string, boolean>
+  pendingDeletePath: string | null
+  actionMessage: string | null
+  diffView: GitDiffView
+  folds: Record<string, Record<string, FoldState>>
+  /** Working-tree-vs-HEAD~N offset. 0 = working tree vs HEAD (default). */
+  headOffset: number
+  /** When true, diff the active workspace's working tree against its fork point. */
+  reviewBase: boolean
+}
+
+interface ModalBase {
+  selectedIndex: number
+  editBuffer: string | null
+  projectTargetId: string | null
+  cursorPos?: number
+  /**
+   * Where the focus goes when this modal closes, when it is not back to the
+   * panes. Set by whoever opened it, because that is who knows what is behind it
+   * — the settings screen opens five different modals, and none of them should
+   * have to grow a case in the reducer to find their way home.
+   */
+  returnTo?: FocusMode
+}
+
+export interface ModalClosed extends ModalBase {
+  type: null
+  editBuffer: null
+  projectTargetId: null
+}
+
+/**
+ * Picking an assistant for a new tab, and nothing else. The tab lands in the
+ * project's active workspace; creating a workspace is `create-workspace`'s job.
+ */
+export interface ModalNewTab extends ModalBase {
+  type: 'new-tab'
+  editingCommand: AssistantId | null
+  /**
+   * Set when `create-workspace` chained into this picker. The prompt the user
+   * typed there is sent to the assistant and drives the workspace's real name,
+   * and the tab is pinned to the freshly created workspace rather than the
+   * project's active one. Living on the modal means `close-modal` clears it, so
+   * escaping the picker cannot leak a stale prompt into a later tab.
+   */
+  pendingWorkspace?: PendingWorkspaceLaunch
+  /**
+   * A prompt to hand the picked assistant, with none of `pendingWorkspace`'s
+   * other behaviour: no workspace pinning, no rename. Used by "Ask an agent" in
+   * the setup widget.
+   */
+  pendingPrompt?: string
+}
+
+export interface PendingWorkspaceLaunch {
+  projectId: string
+  workspaceId: string
+  prompt: string
+}
+
+export interface ModalProjectPicker extends ModalBase {
+  type: 'project-picker'
+}
+
+export interface ModalProjectName extends ModalBase {
+  type: 'project-name'
+  returnToProjectPicker: boolean
+}
+
+export interface ModalRenameTab extends ModalBase {
+  type: 'rename-tab'
+}
+/**
+ * One text field over a settings row. Carries the row it belongs to so confirming
+ * writes back to the right one, and closing returns to the settings screen rather
+ * than to the panes.
+ */
+/** Fuzzy-ish search across every setting, from inside the settings screen. */
+export interface ModalSettingsSearch extends ModalBase {
+  type: 'settings-search'
+}
+export interface ModalSettingText extends ModalBase {
+  type: 'setting-text'
+  settingId: string
+  settingLabel: string
+}
+
+export interface ModalRenameWorkspace extends ModalBase {
+  type: 'rename-workspace'
+  workspaceProjectId: string
+}
+
+export interface ModalSnippetPicker extends ModalBase {
+  type: 'snippet-picker'
+  /**
+   * Transient status line shown at the bottom of the picker (e.g. error from
+   * an open-in-editor attempt). Cleared automatically when the modal closes.
+   */
+  actionMessage?: string | null
+}
+
+export interface ModalThemePicker extends ModalBase {
+  type: 'theme-picker'
+  entryCount: number
+}
+
+export interface ModalHelp extends ModalBase {
+  type: 'help'
+  entryCount: number
+  scope: ModeId | null
+}
+
+export interface ModalSplitPicker extends ModalBase {
+  type: 'split-picker'
+  splitDirection: SplitDirection
+}
+
+export interface ModalGitCommit extends ModalBase {
+  type: 'git-commit'
+  activeField: 'title' | 'body'
+  contentBuffer: string
+  stage: 'edit' | 'generating' | 'confirm'
+}
+
+export interface ModalCreateProject extends ModalBase {
+  type: 'create-project'
+  directoryResults: DirectoryResult[]
+  pendingProjectPath: string | null
+  activeField: 'directory' | 'name'
+  nameBuffer: string
+  returnToProjectPicker: boolean
+}
+
+/**
+ * Creating a workspace inside the current project — the second of the three
+ * creation actions (project / workspace / tab). Deliberately carries no
+ * assistant: once the workspace exists the effect chains into the new-tab modal.
+ */
+export interface ModalCreateWorkspace extends ModalBase {
+  type: 'create-workspace'
+  activeField: 'prompt' | 'base'
+  /**
+   * "What do you want to work on?" — the only thing the user types. It is sent
+   * to the assistant, and it names both the workspace and its branch.
+   */
+  prompt: string
+  branchError: string | null
+  /** Filter text typed into the "Base" picker. */
+  baseQuery: string
+  /** Resolved base ref the new workspace is forked from (a workspace's branch or a local branch). */
+  baseRef: string
+  /** Local branches available as base refs, loaded when the modal opens. */
+  baseBranches: string[]
+}
+
+export interface ModalSnippetEditor extends ModalBase {
+  type: 'snippet-editor'
+  activeField: 'name' | 'trigger' | 'content'
+  /** Persisted value of the name field when it is not the active editor. */
+  nameBuffer: string
+  /** Persisted value of the trigger field when it is not the active editor. */
+  triggerBuffer: string
+  /** Persisted value of the content field when it is not the active editor. */
+  contentBuffer: string
+}
+
+export interface ModalUpdateAvailable extends ModalBase {
+  type: 'update-available'
+  currentVersion: string
+  latestVersion: string
+}
+
+/** The status bar's usage indicator, expanded. Carries nothing: it is a readout. */
+export interface ModalQuotas extends ModalBase {
+  type: 'quotas'
+}
+
+export interface ModalWorkspaceMove extends ModalBase {
+  type: 'workspace-move'
+  /** The workspace being moved (may differ from the active one, e.g. a tab menu). */
+  sourceWorkspaceId: string
+  deleteSource: boolean
+  /** Per-workspace dirty file counts, loaded async when the modal opens. */
+  stats: { kind: 'loading' } | { kind: 'ready'; dirtyFiles: Record<string, number> }
+}
+
+/**
+ * Confirmation for a recoverable move failure: the target's dirty files
+ * overlap the incoming changes (stash-target) or the squash conflicts
+ * (keep-conflicts). Both workspaces are already restored; confirming re-runs
+ * move-workspace with the matching flag.
+ */
+export interface ModalWorkspaceMoveConfirm extends ModalBase {
+  type: 'workspace-move-confirm'
+  variant: 'stash-target' | 'keep-conflicts'
+  files: string[]
+  projectId: string
+  sourceWorkspaceId: string
+  targetWorkspaceId: string
+  deleteSource: boolean
+  sourceLabel: string
+  targetLabel: string
+}
+
+/**
+ * Standalone confirmation for a recoverable workspace delete failure triggered
+ * outside the new-tab picker (e.g. the sidebar's "Remove workspace"). Carries the
+ * params needed to re-run the delete with force once confirmed.
+ */
+export interface ModalWorkspaceDeleteConfirm extends ModalBase {
+  type: 'workspace-delete-confirm'
+  projectId: string
+  workspaceId: string
+  workspaceLabel: string
+  reason?: string
+  closeTabs: boolean
+  /** Whether confirming force-deletes — true only after a recoverable failure. */
+  force: boolean
+}
+
+export type DirectoryResultType = 'git-repo' | 'workspace' | 'project'
+
+export interface DirectoryResult {
+  path: string
+  type: DirectoryResultType
+}
+
+export type FlashJumpTargetKind = 'project' | 'workspace' | 'tab'
+
+export interface FlashJumpTarget {
+  kind: FlashJumpTargetKind
+  /**
+   * 1-based index of the project in the visible project ordering — fed to
+   * the existing `switch-project-by-index` side effect when jumping.
+   */
+  projectIndex: number
+  projectId: string
+  /** Set for kind 'workspace' (the non-primary target) and kind 'tab' (the tab's workspace). */
+  workspaceId?: string
+  /** Set for kind 'tab'. */
+  tabId?: string
+}
+
+export interface FlashLabel {
+  /** Stable identity of the labelled row (`ws:<id>`, `wt:<id>`, `tab:<id>`). */
+  key: string
+  /** 1- or 2-char lowercase ASCII label. */
+  label: string
+  target: FlashJumpTarget
+}
+
+export interface ModalFlashJump extends ModalBase {
+  type: 'flash-jump'
+  labels: FlashLabel[]
+  /** Letters typed so far, narrowing the matching label set. */
+  buffer: string
+  /**
+   * Set by the reducer once the buffer narrows to a single match — read by
+   * app.tsx in a useEffect to perform the actual jump and close the modal.
+   */
+  pendingJump: FlashJumpTarget | null
+}
+
+export interface ModalPlugin extends ModalBase {
+  type: 'plugin-modal'
+  pluginId: string
+  /** Qualified id, `<pluginId>.<modalId>`; the key the registry is read by. */
+  modalId: string
+  /**
+   * Whatever the plugin passed when it opened the modal. Opaque to the
+   * reducer, which is the point: a plugin modal's state is the plugin's.
+   */
+  props?: unknown
+}
+
+export type ModalState =
+  | ModalClosed
+  | ModalNewTab
+  | ModalProjectPicker
+  | ModalProjectName
+  | ModalRenameTab
+  | ModalRenameWorkspace
+  | ModalSnippetPicker
+  | ModalThemePicker
+  | ModalHelp
+  | ModalSplitPicker
+  | ModalCreateProject
+  | ModalCreateWorkspace
+  | ModalSnippetEditor
+  | ModalGitCommit
+  | ModalUpdateAvailable
+  | ModalQuotas
+  | ModalWorkspaceMove
+  | ModalWorkspaceMoveConfirm
+  | ModalWorkspaceDeleteConfirm
+  | ModalFlashJump
+  | ModalSettingText
+  | ModalSettingsSearch
+  | ModalPlugin
+
+export interface LayoutState {
+  terminalCols: number
+  terminalRows: number
+}
+
+export interface SnippetRecord {
+  id: string
+  name: string
+  content: string
+  trigger?: string
+  vars?: Record<string, SnippetVar>
+}
+
+export interface DiscoveredRepo {
+  /** Absolute path to the repo. */
+  path: string
+  /** Label shown in UI (relative to the project root or repo basename). */
+  name: string
+  /** True when the repo is the project's projectPath itself. */
+  isRoot: boolean
+}
+
+export interface MultiRepoState {
+  /** Discovered sub-repos, ordered so root (if any) comes first. */
+  repos: DiscoveredRepo[]
+  /** Precomputed disambiguating prefix per repo path — empty string for the root repo. */
+  prefixes: Record<string, string>
+}
+
+/**
+ * Where the cursor is in the settings screen. Only the cursor: the values being
+ * edited live in `src/settings/settings-store.ts`, or already have a home in
+ * this state (`gitPane`, `customCommands`, …). Duplicating them here would make
+ * two of them.
+ */
+export interface SettingsUIState {
+  /**
+   * Where the cursor is in the screen's one list, counted across every section.
+   * The sections are headings in that list, not a column you move into, so this
+   * is the whole of the screen's state.
+   */
+  rowIndex: number
+}
+
+/**
+ * Where the cursor is on the stats screen. Nothing measured lives here — the
+ * numbers are read from disk by the pages that render them.
+ */
+export interface StatsUIState {
+  pageIndex: number
+  /** Rows scrolled from the top of the current page. Reset when the page changes. */
+  scrollTop: number
+}
+
+export interface AppState {
+  tabs: TabSession[]
+  activeTabId: string | null
+  layoutTrees: Record<string, LayoutNode>
+  tabGroupMap: Record<string, string>
+  projects: ProjectRecord[]
+  currentProjectId: string | null
+  projectStatuses: Record<string, ProjectStatus>
+  projectBar: ProjectBarState
+  snippets: SnippetRecord[]
+  focusMode: FocusMode
+  bars: BarsState
+  gitPane: GitPaneState
+  modal: ModalState
+  layout: LayoutState
+  customCommands: Record<AssistantId, string>
+  gitPanel: GitPanelState
+  gitMode: GitModeState
+  autoCommit: AutoCommitState
+  multiRepo: MultiRepoState
+  settings: SettingsUIState
+  stats: StatsUIState
+  /**
+   * Commits each workspace's branch is ahead/behind the ref it forked from,
+   * keyed by workspace id. Ephemeral (polled); not persisted to the catalog.
+   */
+  workspaceDivergence: Record<string, BranchDivergence>
+  /**
+   * What each workspace's assistants are doing, keyed by workspace id. Covers
+   * every project the daemon knows, not just the current one — see
+   * `src/app-runtime/workspace-activity.ts`, which owns the aggregation.
+   * Ephemeral; not persisted to the catalog.
+   */
+  workspaceActivity: Record<string, WorkspaceActivity>
+  /**
+   * Last active tab a user viewed within each workspace, keyed by workspace id.
+   * Lets switching back to a workspace restore its last-viewed tab instead of
+   * snapping to the first one. Ephemeral (in-memory); not persisted to the catalog.
+   */
+  lastActiveTabByWorkspace: Record<string, string>
+  /** Chord prefix the sequence resolver is currently waiting on, or null when idle. */
+  pendingChords: string[] | null
+  /**
+   * The plugin pane holding the keyboard, by its qualified id, or null when a
+   * terminal has it.
+   *
+   * Kept alongside `activeTabId` rather than replacing it: every reducer and
+   * every side effect in the app reads `activeTabId` as *a tab*, and widening
+   * it would mean auditing all of them for "what if this is not one". So the
+   * terminal stays named, the pane says it has the keys, and moving focus back
+   * to any tab clears this.
+   */
+  activePluginPaneId: string | null
+  /**
+   * The plugin view currently replacing the panes, by its qualified id
+   * (`<pluginId>.<viewId>`), or null. Only meaningful while `focusMode` is
+   * `plugin-view`; kept alongside rather than inside it so the focus union
+   * does not have to grow an arm per view.
+   */
+  activePluginView: string | null
+  /**
+   * One namespaced slice per plugin, keyed by plugin id. Opaque to the core
+   * reducer: a plugin registers a reducer for its own key and nothing else
+   * reads or writes it. Namespacing rather than a flat merge is what keeps a
+   * plugin from colliding with the app — or with another plugin — over a
+   * state key.
+   */
+  plugins: Record<string, unknown>
+  /**
+   * Bumped whenever a plugin registry changes — a widget registered, a view
+   * withdrawn, a fiber reloaded. Components that read a registry rather than
+   * the store subscribe to this so a hot reload repaints them; without it a
+   * reloaded widget would keep rendering its previous closure until something
+   * unrelated re-rendered the tree.
+   */
+  pluginRegistryVersion: number
+}
+
+// -- Git panel payloads --
+export interface GitRefreshPayload {
+  branch: string | null
+  ahead: number
+  behind: number
+  files: GitFileEntry[]
+}
+
+/** Commits a workspace branch is ahead/behind the ref it forked from. */
+export interface BranchDivergence {
+  ahead: number
+  behind: number
+  /** Lines changed since the fork point, working tree included. */
+  added?: number
+  removed?: number
+}
+
+// -- Auto-commit state --
+export type AutoCommitSuggestion =
+  | { kind: 'idle' }
+  | {
+      kind: 'generating'
+      tabId: string
+      workingTreeHash: string
+      abortController: AbortController
+      startedAt: number
+    }
+  | {
+      kind: 'ready'
+      tabId: string
+      workingTreeHash: string
+      title: string
+      body: string
+      generatedAt: number
+    }
+
+export interface AutoCommitState {
+  byProject: Record<string, AutoCommitSuggestion>
+}
+
+// ─── Modes, key results and side effects ──────────────────────────────────────
+
+/**
+ * The modes aimux ships. `ModeId` is this plus the plugin namespace, so a
+ * `switch` over a built-in mode stays exhaustive while a plugin can still
+ * introduce one of its own.
+ */
+export type BuiltinModeId =
+  | 'navigation'
+  | 'terminal-input'
+  | 'git-mode'
+  | 'modal.new-tab.command-edit'
+  | 'modal.new-tab.editing-command'
+  | 'modal.workspace-delete-confirm'
+  | 'modal.project-picker.filtering'
+  | 'modal.project-name'
+  | 'modal.create-project'
+  | 'modal.create-workspace'
+  | 'modal.rename-tab'
+  | 'modal.rename-workspace'
+  | 'modal.setting-text'
+  | 'modal.settings-search.filtering'
+  | 'modal.snippet-picker.filtering'
+  | 'modal.snippet-editor'
+  | 'modal.theme-picker.filtering'
+  | 'modal.help.filtering'
+  | 'modal.split-picker'
+  | 'modal.git-commit'
+  | 'modal.git-commit.confirm'
+  | 'modal.git-commit.generating'
+  | 'modal.update-available'
+  | 'modal.workspace-move'
+  | 'modal.workspace-move-confirm'
+  | 'modal.flash-jump'
+  | 'modal.quotas'
+  | 'settings'
+  | 'stats'
+
+/**
+ * A mode a plugin owns. Namespaced by plugin id — `plugin.acme.thing.review` —
+ * so two plugins can each have a "review" mode, and so the owner of an
+ * unexpected mode id is readable from the id alone.
+ */
+export type PluginModeId = `plugin.${string}`
+
+export type ModeId = BuiltinModeId | PluginModeId
+
+/**
+ * The effect half of the plugin envelope; see `PluginStateAction` for the
+ * action half. Same reasoning: the union stays closed so the 68-branch
+ * executor keeps its exhaustiveness check, and a plugin's effect is routed by
+ * `pluginId` to the handler that plugin registered.
+ */
+export interface PluginSideEffect {
+  type: 'plugin-effect'
+  pluginId: string
+  effectId: string
+  payload?: unknown
+}
+
+export type SideEffect =
+  | { type: 'quit'; state: AppState }
+  | { type: 'open-new-tab' }
+  | { type: 'launch-selected-assistant' }
+  | { type: 'edit-selected-assistant' }
+  | { type: 'confirm-selected-project' }
+  | { type: 'delete-selected-project' }
+  | { type: 'open-rename-selected-project' }
+  | { type: 'create-project'; name: string; projectPath?: string }
+  | { type: 'create-workspace' }
+  | { type: 'load-create-workspace-base-branches' }
+  | { type: 'close-tab'; tabId: string }
+  | { type: 'restart-tab'; tab: TabSession }
+  | { type: 'paste-selected-snippet' }
+  | { type: 'paste-snippet-to-group' }
+  | { type: 'edit-selected-snippet' }
+  | { type: 'delete-selected-snippet' }
+  | { type: 'save-snippet-editor' }
+  | { type: 'save-custom-command' }
+  | { type: 'apply-theme'; action: 'open' }
+  | { type: 'apply-theme'; action: 'restore' }
+  | { type: 'apply-theme'; action: 'confirm' }
+  | { type: 'apply-theme'; action: 'preview'; delta: 1 | -1 }
+  | { type: 'rename-project'; projectId: string; name: string }
+  | { type: 'rename-tab'; tabId: string; title: string }
+  | {
+      type: 'split-pane'
+      direction: SplitDirection
+      sourceTabId?: string
+    }
+  | { type: 'confirm-split' }
+  | { type: 'scroll-git-diff'; delta: number }
+  | { type: 'persist-git-diff-mode-ratio'; ratio: number }
+  | { type: 'persist-git-file-list-mode'; mode: GitFileListMode }
+  | { type: 'persist-git-tree-compaction'; enabled: boolean }
+  | { type: 'git-stage'; path: string }
+  | { type: 'git-unstage'; path: string }
+  | { type: 'git-stage-all' }
+  | { type: 'git-unstage-all' }
+  | { type: 'git-restore'; path: string }
+  | { type: 'git-rm'; path: string }
+  | { type: 'git-commit'; title: string; body: string }
+  | { type: 'git-commit-auto'; title: string; body: string }
+  | { type: 'generate-auto-commit-now'; projectId: string }
+  | { type: 'git-push' }
+  | { type: 'confirm-update-selection' }
+  | { type: 'switch-project-by-index'; index: number; workspaceId?: string }
+  | { type: 'cycle-sidebar-item'; direction: 1 | -1 }
+  | { type: 'switch-tab-by-index'; index: number }
+  | { type: 'delete-project'; projectId: string }
+  | {
+      type: 'delete-workspace'
+      projectId: string
+      workspaceId: string
+      // Force the git worktree removal (discards uncommitted changes in the
+      // workspace). Also implies closing the workspace's tabs.
+      force?: boolean
+      // Close the workspace's tabs without forcing the git removal. Lets the
+      // sidebar "Remove workspace" clean up tabs (avoiding orphans) while still
+      // refusing to discard uncommitted work in a temp workspace.
+      closeTabs?: boolean
+    }
+  | {
+      type: 'move-workspace'
+      projectId: string
+      sourceWorkspaceId: string
+      targetWorkspaceId: string
+      deleteSource?: boolean
+      // Retry flags set by the workspace-move-confirm dialog.
+      stashTarget?: boolean
+      keepConflicts?: boolean
+    }
+  | { type: 'load-workspace-move-stats' }
+  | { type: 'hibernate-workspace'; workspaceId: string }
+  | { type: 'toggle-transparent' }
+  | { type: 'toggle-mode' }
+  | { type: 'open-file-in-editor'; path: string }
+  | { type: 'open-selected-snippet-source-in-editor' }
+  | { type: 'run-setup' }
+  | { type: 'stop-setup' }
+  | { type: 'configure-setup-script'; projectId?: string }
+  | { type: 'set-project-default-base-ref'; projectId: string; baseRef: string }
+  | { type: 'toggle-project-collapsed'; projectId: string }
+  | { type: 'ask-agent-for-setup-script' }
+  | { type: 'promote-setup-tab' }
+  /** Toggle a checkbox, cycle an enum, run a row's action — whatever the row is. */
+  | { type: 'activate-settings-row' }
+  | { type: 'adjust-settings-row'; delta: 1 | -1 }
+  | { type: 'reset-settings-row' }
+  | { type: 'confirm-settings-search' }
+  | { type: 'commit-setting-text'; settingId: string; value: string }
+  | PluginSideEffect
+
+export interface KeyResult {
+  actions: AppAction[]
+  effects: SideEffect[]
+  transition?: ModeId
+}
+
+export interface ModeContext {
+  readonly state: AppState
+}
+
+/**
+ * The subset of opentui's `KeyEvent` the keymap layer reads. Declared
+ * structurally rather than as a `Pick<KeyEvent, …>` so this package keeps no
+ * runtime dependency on `@opentui/core`; `src/input/modes/types.ts` asserts
+ * the two agree, so a change on opentui's side fails the build here.
+ */
+export interface KeyInput {
+  name: string
+  ctrl: boolean
+  meta: boolean
+  shift: boolean
+  sequence: string
+}
+
+// ─── AppAction union ──────────────────────────────────────────────────────────
+
+export type ModalAction =
+  | {
+      type: 'move-modal-cursor'
+      delta?: number
+      to?: 'end' | 'home' | 'line-down' | 'line-up' | 'word-left' | 'word-right'
+    }
+  | {
+      type: 'open-new-tab-modal'
+      pendingWorkspace?: PendingWorkspaceLaunch
+      pendingPrompt?: string
+    }
+  | { type: 'open-edit-custom-command'; assistantId: AssistantId }
+  | { type: 'open-help-modal'; scope?: ModeId }
+  | { type: 'open-split-picker'; direction: SplitDirection }
+  | { type: 'open-project-picker' }
+  | {
+      type: 'open-project-name-modal'
+      projectTargetId?: string
+      initialName?: string
+      returnToProjectPicker?: boolean
+    }
+  | { type: 'close-modal' }
+  | { type: 'move-modal-selection'; delta: number }
+  | { type: 'update-command-edit'; char: string }
+  | { type: 'cancel-command-edit' }
+  | { type: 'open-create-project-modal'; returnToProjectPicker: boolean }
+  | { type: 'open-create-workspace-modal' }
+  | { type: 'set-create-workspace-base-branches'; branches: string[]; defaultBranch?: string }
+  | { type: 'set-create-workspace-branch-error'; message: string | null }
+  | { type: 'switch-create-workspace-field' }
+  | { type: 'set-directory-results'; results: DirectoryResult[] }
+  | { type: 'switch-create-project-field' }
+  | { type: 'select-directory' }
+  | { type: 'open-rename-tab-modal' }
+  | {
+      type: 'open-rename-workspace-modal'
+      projectId: string
+      workspaceId: string
+      initialName: string
+    }
+  | { type: 'open-snippet-picker'; returnTo?: FocusMode }
+  | { type: 'open-snippet-editor'; snippetId?: string }
+  | { type: 'set-help-entry-count'; count: number }
+  | { type: 'set-theme-entry-count'; count: number }
+  | { type: 'open-theme-picker'; returnTo?: FocusMode }
+  | { type: 'open-update-available-modal'; currentVersion: string; latestVersion: string }
+  | { type: 'open-quotas-modal' }
+  | { type: 'set-modal-selection-index'; index: number }
+  | { type: 'open-workspace-move-modal'; sourceWorkspaceId: string }
+  | { type: 'toggle-workspace-move-delete' }
+  | { type: 'set-workspace-move-stats'; dirtyFiles: Record<string, number> }
+  | {
+      type: 'open-workspace-move-confirm'
+      variant: 'stash-target' | 'keep-conflicts'
+      files: string[]
+      projectId: string
+      sourceWorkspaceId: string
+      targetWorkspaceId: string
+      deleteSource: boolean
+      sourceLabel: string
+      targetLabel: string
+    }
+  | {
+      type: 'open-workspace-delete-confirm'
+      projectId: string
+      workspaceId: string
+      workspaceLabel: string
+      reason?: string
+      closeTabs: boolean
+      force: boolean
+    }
+  | { type: 'open-flash-jump-modal' }
+  | { type: 'clear-flash-jump-pending' }
+
+export type ProjectAction =
+  | {
+      type: 'load-project'
+      projectId: string
+      projectSnapshot?: ProjectSnapshotV1
+      forceDisconnected?: boolean
+    }
+  | { type: 'set-projects'; projects: ProjectRecord[] }
+  | { type: 'create-project-record'; project: ProjectRecord }
+  | { type: 'rename-project-record'; projectId: string; name: string }
+  | { type: 'delete-project-record'; projectId: string; openProjectPicker?: boolean }
+  | { type: 'reorder-projects'; orderedIds: string[] }
+  | { type: 'reorder-active-project'; delta: number }
+  | { type: 'set-project-status'; projectId: string; status: ProjectStatus }
+  /** What a workspace's assistants are doing. `done` is owned by the reducer,
+   *  so this carries only the two flags derived from tab statuses. */
+  | { type: 'set-workspace-activity'; workspaceId: string; working: boolean; waiting: boolean }
+  /** An assistant in this workspace finished a turn and nobody has looked yet. */
+  | { type: 'mark-workspace-done'; workspaceId: string }
+  /** The tab that rang: it finished a turn while the user was elsewhere. */
+  | { type: 'mark-tab-unseen'; tabId: string }
+  | {
+      type: 'add-workspace-record'
+      projectId: string
+      workspace: WorkspaceRecord
+      activate?: boolean
+    }
+  | { type: 'set-active-workspace'; projectId: string; workspaceId: string }
+  | {
+      type: 'update-workspace-record'
+      projectId: string
+      workspaceId: string
+      patch: Partial<WorkspaceRecord>
+    }
+
+export type TabAction =
+  | { type: 'add-tab'; tab: TabSession }
+  | {
+      type: 'hydrate-project'
+      tabs: TabSession[]
+      activeTabId: string | null
+      layoutTree?: LayoutNode | null
+      layoutTrees?: Record<string, LayoutNode>
+      tabGroupMap?: Record<string, string>
+    }
+  | { type: 'close-tab'; tabId: string }
+  | { type: 'close-active-tab' }
+  | { type: 'set-active-tab'; tabId: string }
+  | { type: 'move-active-tab'; delta: number }
+  | { type: 'reorder-active-tab'; delta: number }
+  | { type: 'reorder-tabs'; orderedTabIds: string[] }
+  | { type: 'reset-tab-project'; tabId: string }
+  | { type: 'hibernate-tab'; tabId: string }
+  | {
+      type: 'rename-tab'
+      tabId: string
+      title: string
+      autoRenameStatus?: 'eligible' | 'attempted'
+    }
+  | {
+      type: 'update-tab-metadata'
+      tabId: string
+      title?: string
+      autoRenameStatus?: 'eligible' | 'attempted'
+      /** Set to false to promote a hidden tab into the normal tab strip. */
+      hidden?: boolean
+    }
+  | { type: 'append-tab-buffer'; tabId: string; chunk: string }
+  | {
+      type: 'replace-tab-viewport'
+      tabId: string
+      viewport: TerminalSnapshot
+      terminalModes: TerminalModeState
+      source?: 'resize' | 'scroll' | 'data' | 'switch'
+    }
+  | { type: 'set-tab-activity'; tabId: string; activity?: TabActivity }
+  | { type: 'set-tab-error'; tabId: string; message: string }
+
+export type LayoutAction =
+  | {
+      type: 'split-pane'
+      direction: SplitDirection
+      newTab: TabSession
+    }
+  | { type: 'close-pane'; tabId: string }
+  | {
+      type: 'focus-pane-direction'
+      direction: 'left' | 'right' | 'up' | 'down'
+    }
+  | {
+      type: 'resize-pane'
+      tabId: string
+      delta: number
+      axis?: SplitDirection
+    }
+  | {
+      type: 'set-split-ratio'
+      tabId: string
+      ratio: number
+      axis?: SplitDirection
+    }
+  /**
+   * Splits the active pane and puts a plugin's renderer beside it. Two
+   * concrete arms rather than another routed `plugin-*` variant: where a pane
+   * goes and when it closes is the layout's business, not the plugin's, and
+   * the reducer has to reason about both.
+   */
+  | {
+      type: 'open-plugin-pane'
+      /** Qualified `<pluginId>.<paneId>`. */
+      paneId: string
+      direction: SplitDirection
+    }
+  | { type: 'close-plugin-pane'; paneId: string }
+
+export type UIAction =
+  | { type: 'toggle-bar'; side: BarSide }
+  | { type: 'resize-bar'; side: BarSide; delta: number }
+  | { type: 'set-bar-width'; side: BarSide; width: number }
+  | { type: 'toggle-widget'; widgetId: string }
+  | {
+      type: 'add-widget'
+      widgetId: string
+      side: BarSide
+      /** Defaults to the end of the bar. */
+      index?: number
+      grow?: number
+      placedBy?: 'plugin'
+    }
+  | { type: 'remove-plugin-widget'; widgetId: string }
+  | { type: 'move-widget'; widgetId: string; side: BarSide; index: number }
+  | { type: 'set-bar-boundary'; side: BarSide; index: number; ratio: number }
+  | { type: 'resize-widget'; widgetId: string; delta: number }
+  | { type: 'set-focus-mode'; focusMode: FocusMode }
+  | { type: 'set-terminal-size'; cols: number; rows: number }
+  | { type: 'resize-git-diff-pane'; delta: number }
+  | { type: 'set-pending-chords'; chords: string[] | null }
+  | { type: 'toggle-project-bar' }
+
+export type SettingsAction =
+  | { type: 'enter-settings' }
+  | { type: 'exit-settings' }
+  | { type: 'settings-move-selection'; delta: -1 | 1 }
+  | { type: 'settings-jump-section'; delta: -1 | 1 }
+  | { type: 'settings-select-row'; rowIndex: number }
+  | { type: 'open-settings-search' }
+  | { type: 'open-setting-text-modal'; settingId: string; label: string; value: string }
+
+export type StatsAction =
+  | { type: 'enter-stats' }
+  | { type: 'exit-stats' }
+  | { type: 'stats-move-page'; delta: -1 | 1 }
+  | { type: 'stats-select-page'; pageIndex: number }
+  /** Rows, not pixels: the view holds a scroll offset the page applies to its box. */
+  | { type: 'stats-scroll'; delta: number }
+  /** The offset the scrollbox actually accepted, sent back so the state cannot run past the page. */
+  | { type: 'stats-scroll-settled'; scrollTop: number }
+
+export type GitPanelAction =
+  | { type: 'git-refresh-success'; payload: GitRefreshPayload }
+  | { type: 'git-refresh-error'; kind: GitPanelError }
+  | { type: 'git-panel-reset' }
+  | { type: 'set-workspace-divergence'; divergence: Record<string, BranchDivergence> }
+  | { type: 'set-git-pane'; patch: Partial<GitPaneState> }
+
+export type AutoCommitAction =
+  | {
+      type: 'auto-commit-generation-started'
+      projectId: string
+      tabId: string
+      workingTreeHash: string
+      abortController: AbortController
+      startedAt: number
+    }
+  | {
+      type: 'auto-commit-generation-ready'
+      projectId: string
+      workingTreeHash: string
+      title: string
+      body: string
+      generatedAt: number
+    }
+  | { type: 'auto-commit-clear'; projectId: string }
+
+export type GitModeAction =
+  | { type: 'enter-git-mode' }
+  | { type: 'exit-git-mode' }
+  | { type: 'git-mode-move-selection'; delta: -1 | 1 }
+  | { type: 'git-mode-move-file-selection'; delta: -1 | 1 }
+  | { type: 'git-mode-select-entry-by-key'; key: string }
+  | { type: 'git-mode-toggle-folder'; key: string }
+  | { type: 'git-mode-toggle-selected-folder' }
+  | { type: 'git-mode-collapse-selection' }
+  | { type: 'git-mode-expand-selection' }
+  | { type: 'git-mode-toggle-file-list-mode' }
+  | { type: 'git-mode-toggle-tree-compaction' }
+  | { type: 'git-mode-set-diff'; key: string; diff: DiffData; hash: string }
+  | {
+      type: 'git-mode-set-parsed'
+      key: string
+      hash: string
+      file: unknown
+    }
+  | {
+      type: 'git-mode-set-highlights'
+      key: string
+      hash: string
+      themeId: string
+      add: unknown
+      del: unknown
+    }
+  | {
+      type: 'git-mode-merge-highlights'
+      key: string
+      hash: string
+      themeId: string
+      add: { start: number; tokens: unknown }[]
+      del: { start: number; tokens: unknown }[]
+    }
+  | { type: 'git-mode-invalidate-diffs'; paths: string[] }
+  | { type: 'git-mode-set-loading'; key: string; loading: boolean }
+  | { type: 'git-mode-set-pending-delete'; path: string | null }
+  | { type: 'git-mode-clear-diff-cache'; path: string }
+  | { type: 'git-mode-set-message'; message: string | null }
+  | { type: 'snippet-picker-set-message'; message: string | null }
+  | { type: 'git-mode-toggle-diff-view' }
+  | { type: 'git-mode-toggle-review-base' }
+  | { type: 'git-mode-shift-head-offset'; delta: number }
+  | { type: 'git-mode-set-head-offset'; offset: number }
+  | {
+      type: 'git-mode-fold-adjust'
+      key: string
+      foldId: string
+      side: 'top' | 'bottom'
+      delta: number
+    }
+  | { type: 'git-mode-fold-set'; key: string; foldId: string; top: number; bottom: number }
+  | { type: 'git-mode-fold-toggle-all'; key: string }
+  | {
+      type: 'git-mode-optimistic-move'
+      path: string
+      fromSection: GitFileSection
+      toSection: GitFileSection | null
+    }
+  | { type: 'open-git-commit-modal'; projectId?: string }
+  | { type: 'git-commit-enter-confirm' }
+  | { type: 'git-commit-leave-confirm' }
+  | { type: 'git-commit-enter-generating'; projectId: string }
+  | { type: 'git-commit-leave-generating' }
+  | { type: 'git-commit-use-background-suggestion'; projectId: string }
+
+export type DataAction =
+  | { type: 'set-snippets'; snippets: SnippetRecord[] }
+  | { type: 'delete-snippet'; snippetId: string }
+  | { type: 'set-custom-commands'; customCommands: Record<AssistantId, string> }
+
+export type MultiRepoAction =
+  | { type: 'multi-repo-set-repos'; repos: DiscoveredRepo[] }
+  | { type: 'multi-repo-clear' }
+
+/**
+ * The one variant a plugin dispatches. `AppAction` stays a closed union — the
+ * exhaustiveness check across every reducer is worth more than the ability to
+ * add arms to it — so a plugin's own action travels inside this envelope and
+ * is routed to that plugin's slice reducer by `pluginId`.
+ */
+export type PluginStateAction =
+  | { type: 'plugin-action'; pluginId: string; actionId: string; payload?: unknown }
+  /** Replaces a plugin's whole slice. Used on load, and on unload to drop it. */
+  | { type: 'set-plugin-slice'; pluginId: string; slice: unknown }
+  /** Signals that some plugin registry changed; see `pluginRegistryVersion`. */
+  | { type: 'bump-plugin-registry' }
+  /** Replaces the panes with a plugin's full-screen view. */
+  | { type: 'open-plugin-view'; viewId: string }
+  /** Returns from a plugin view to the panes. */
+  | { type: 'close-plugin-view' }
+  /** Opens a plugin's modal over whatever is on screen. `close-modal` closes it. */
+  | {
+      type: 'open-plugin-modal'
+      pluginId: string
+      modalId: string
+      props?: unknown
+      returnTo?: FocusMode
+    }
+
+export type AppAction =
+  | ModalAction
+  | ProjectAction
+  | TabAction
+  | LayoutAction
+  | UIAction
+  | SettingsAction
+  | StatsAction
+  | DataAction
+  | GitPanelAction
+  | GitModeAction
+  | AutoCommitAction
+  | MultiRepoAction
+  | PluginStateAction