@brimveyn/aimux 1.22.3 → 1.22.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.22.3",
+  "version": "1.22.5",
   "description": "A terminal multiplexer for AI CLIs. Run Claude, Codex, OpenCode, Kimi side-by-side with tabbed navigation, split panes, and persistent sessions.",
   "keywords": [
     "ai",

package/src/app-runtime/side-effects.ts

@@ -8,7 +8,7 @@ import { loadConfig, saveConfig } from '../config'
 import { logInputDebug } from '../debug/input-log'
 import { enqueueGitOp } from '../git/command-queue'
 import { countDirtyFiles } from '../git/move-workspace'
-import { getDefaultBranch, listLocalBranches } from '../git/worktree'
+import { getCurrentBranch, getDefaultBranch, listLocalBranches } from '../git/worktree'
 import { assistantAcceptsPromptArg } from '../pty/command-registry'
 import { allLeafIds, getGroupIdForTab } from '../state/layout-tree'
 import { saveCurrentProject } from '../state/project-save'
@@ -72,6 +72,7 @@ import {
   isForceableWorkspaceDeleteError,
   runDeleteWorkspace,
   runMoveWorkspace,
+  setProjectDefaultBaseRef,
 } from './workspace-actions'
 import { placeholderWorkspaceName, renameWorkspaceFromPrompt } from './workspace-naming'
 
@@ -207,6 +208,12 @@ function applyThemeEffect(
   }
 }
 
+/** The given branch first, the rest in the order they came. */
+function hoistBranch(branches: string[], first: string | undefined): string[] {
+  if (first == null || !branches.includes(first)) return branches
+  return [first, ...branches.filter((branch) => branch !== first)]
+}
+
 /**
  * Setup runs concurrently with the agent by design, so say so rather than
  * letting the agent run tests against a half-installed tree and draw the wrong
@@ -359,12 +366,21 @@ export function executeSideEffect(effect: SideEffect, ctx: SideEffectContext): v
         const project = state.projects.find((entry) => entry.id === state.currentProjectId)
         const sourcePath = getActiveWorkspace(project)?.path ?? getActiveWorkspacePath(project)
         if (!(sourcePath != null && sourcePath !== '')) return
-        const [branches, defaultBranch] = await Promise.all([
+        const [branches, defaultBranch, currentBranch] = await Promise.all([
           listLocalBranches(sourcePath),
           getDefaultBranch(sourcePath),
+          getCurrentBranch(sourcePath),
         ])
         if (ctx.getState().modal.type !== 'create-workspace') return
-        ctx.dispatch({ branches, defaultBranch, type: 'set-create-workspace-base-branches' })
+        ctx.dispatch({
+          // Stacking on the branch you are already on is the other common base,
+          // and committer date buries it once anyone else pushes.
+          branches: hoistBranch(branches, currentBranch),
+          // The project's convention wins over what the repo declares: a gitflow
+          // repo still says `main` while everyone branches off `develop`.
+          defaultBranch: project?.defaultBaseRef ?? defaultBranch,
+          type: 'set-create-workspace-base-branches',
+        })
       })()
       return
     }
@@ -678,6 +694,10 @@ export function executeSideEffect(effect: SideEffect, ctx: SideEffectContext): v
       handleConfigureSetupScriptEffect(ctx, effect.projectId)
       return
     }
+    case 'set-project-default-base-ref': {
+      setProjectDefaultBaseRef(ctx, effect.projectId, effect.baseRef)
+      return
+    }
     case 'ask-agent-for-setup-script': {
       handleAskAgentForSetupScriptEffect(ctx)
       return
@@ -729,11 +749,18 @@ function runUpdateFromTui(ctx: SideEffectContext, latestVersion: string): void {
   void ctx.backend.destroy(true)
   ctx.renderer.destroy()
   process.stdout.write(`\nUpdating aimux to ${latestVersion}...\n`)
-  const proc = Bun.spawn(['bun', 'update', '-g', '@brimveyn/aimux', '@brimveyn/aimux-config'], {
-    stderr: 'inherit',
-    stdin: 'inherit',
-    stdout: 'inherit',
-  })
+  // `bun update -g` is a no-op when the global entry pins an exact version
+  // (`"@brimveyn/aimux": "1.22.2"`), which is what `install -g pkg@version`
+  // writes — the update "succeeded", the version never moved, and the modal
+  // came back every launch. Install the resolved version explicitly instead.
+  const proc = Bun.spawn(
+    ['bun', 'install', '-g', `@brimveyn/aimux@${latestVersion}`, '@brimveyn/aimux-config@latest'],
+    {
+      stderr: 'inherit',
+      stdin: 'inherit',
+      stdout: 'inherit',
+    }
+  )
   void (async () => {
     const code = await proc.exited
     if (code === 0) {

package/src/app-runtime/workspace-actions.ts

@@ -23,6 +23,7 @@ import {
   makeWorktreePath,
   sanitizePathSegment,
 } from '../platform/worktree-paths'
+import { shouldRefreshBase } from '../settings/flags'
 import { saveProjectCatalog } from '../state/project-catalog'
 import { pruneSnapshotOfWorkspace } from '../state/project-persistence'
 import { getActiveWorkspace, getActiveWorkspacePath } from '../state/project-workspaces'
@@ -64,6 +65,27 @@ export function handleSwitchWorkspace(
   ctx.dispatch({ projects, type: 'set-projects' })
 }
 
+/**
+ * Set (or clear, when blank) the branch this project's new workspaces fork from.
+ * Here rather than with the project actions: the value is workspace policy that
+ * happens to be stored on the project, and this is where the record-update
+ * helper and the rest of that policy already live.
+ */
+export function setProjectDefaultBaseRef(
+  ctx: SideEffectContext,
+  projectId: string,
+  baseRef: string
+): void {
+  const trimmed = baseRef.trim()
+  const projects = replaceProject(ctx, projectId, (entry) => ({
+    ...entry,
+    defaultBaseRef: trimmed === '' ? undefined : trimmed,
+    updatedAt: new Date().toISOString(),
+  }))
+  saveProjectCatalog(projects)
+  ctx.dispatch({ projects, type: 'set-projects' })
+}
+
 function normalizeBranchName(branch: string | undefined): string | undefined {
   return branch?.replace(/^refs\/heads\//, '').trim()
 }
@@ -116,11 +138,19 @@ export async function createAimuxTempWorkspace(
 
   await mkdir(dirname(targetPath), { recursive: true })
   await assertSafeAimuxWorktreePath(targetPath)
-  await createGitWorktree({ baseRef, branchName, repoPath: repoRoot, targetPath })
+  // What it forked from, not what was asked for: the two differ whenever the
+  // base was refreshed from origin, and the record is what "based on" reads.
+  const forkRef = await createGitWorktree({
+    baseRef,
+    branchName,
+    refreshBase: shouldRefreshBase(),
+    repoPath: repoRoot,
+    targetPath,
+  })
   const now = new Date().toISOString()
 
   const workspace: WorkspaceRecord = {
-    baseRef,
+    baseRef: forkRef,
     branch: branchName,
     commitSha: await getHeadSha(targetPath),
     createdAt: now,

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

@@ -10,6 +10,7 @@ import {
   makeWorktreePath,
   pruneEmptyWorktreeParent,
 } from '../../../platform/worktree-paths'
+import { shouldRefreshBase } from '../../../settings/flags'
 
 export interface CreateWorkspaceParams {
   /** Base ref for the branch (callers default to 'HEAD'). */
@@ -68,10 +69,12 @@ export async function createProjectWorkspace(
   await ensureAimuxWorktreeRoot()
   await assertSafeAimuxWorktreePath(targetPath)
 
+  let forkRef: string
   try {
-    await createGitWorktree({
+    forkRef = await createGitWorktree({
       baseRef: base,
       branchName: branch,
+      refreshBase: shouldRefreshBase(),
       repoPath: primary.repoRoot,
       targetPath,
     })
@@ -84,7 +87,8 @@ export async function createProjectWorkspace(
 
   const now = new Date().toISOString()
   const record: WorkspaceRecord = {
-    baseRef: base,
+    // What it forked from: `origin/<base>` when the base was refreshed.
+    baseRef: forkRef,
     branch,
     createdAt: now,
     createdByAimux: true,

package/src/git/worktree.ts

@@ -98,9 +98,48 @@ export async function renameGitBranch(
   return result.exitCode === 0
 }
 
+/**
+ * The ref a new workspace should actually fork from.
+ *
+ * "Base it on main" means the main the team pushed, not whatever the local main
+ * happened to be at the last pull — a workspace started ten commits behind says
+ * nothing at the time and shows up as conflicts at merge. So fetch the base's
+ * counterpart on origin and fork from that when there is one.
+ *
+ * Every step is best-effort on purpose. The fetch is `nothrow`, so a machine
+ * with no network still gets a workspace off the local ref; and a base with no
+ * counterpart on origin — a local-only branch, a SHA, `HEAD`, or an
+ * already-qualified `origin/x` — resolves to nothing and is used as given, which
+ * is why no ref-shape guessing is needed here.
+ *
+ * The refspec is spelled out rather than left to `remote.origin.fetch`: a bare
+ * `fetch origin main` on a remote with no configured refspec updates only
+ * FETCH_HEAD, leaving a stale `origin/main` that resolves perfectly well — so
+ * the fork would silently land on exactly the old commit this exists to avoid.
+ *
+ * ponytail: unpushed commits on the local base are unreachable from the picker
+ * once this is on — the remote ref wins whenever it exists, and the toggle is
+ * the only way back. Listing `main` and `origin/main` as separate base options
+ * is the upgrade path.
+ */
+export async function resolveWorktreeBaseRef(repoPath: string, baseRef: string): Promise<string> {
+  const remoteRef = `origin/${baseRef}`
+  await $`git -C ${repoPath} fetch origin +${baseRef}:refs/remotes/${remoteRef}`.quiet().nothrow()
+  return (await resolveGitRef(repoPath, remoteRef)) !== undefined ? remoteRef : baseRef
+}
+
+/**
+ * Returns the ref it forked from, which is not always the one it was handed.
+ *
+ * `refreshBase` is required rather than read from the user's config here: this
+ * module wraps git and nothing else, and a caller that has to name the policy
+ * cannot forget it exists — which a settings lookup hidden in here would let
+ * them do. `shouldRefreshBase` is what both callers name it with.
+ */
 export async function createGitWorktree({
   baseRef,
   branchName,
+  refreshBase,
   repoPath,
   targetPath,
 }: {
@@ -108,10 +147,18 @@ export async function createGitWorktree({
   targetPath: string
   branchName: string
   baseRef: string
-}): Promise<void> {
-  const result = await $`git -C ${repoPath} worktree add -b ${branchName} ${targetPath} ${baseRef}`
-    .quiet()
-    .nothrow()
+  refreshBase: boolean
+}): Promise<string> {
+  const forkRef = refreshBase ? await resolveWorktreeBaseRef(repoPath, baseRef) : baseRef
+  // `--no-track`: forking from `origin/main` would otherwise set that as the new
+  // branch's upstream, and a workspace branch tracking main is not a workspace
+  // branch — `git push` either refuses it (push.default=simple) or, worse,
+  // pushes the branch onto main. Forking from a local branch never set tracking,
+  // so this only pins down what refreshing the base would have changed.
+  const result =
+    await $`git -C ${repoPath} worktree add --no-track -b ${branchName} ${targetPath} ${forkRef}`
+      .quiet()
+      .nothrow()
   if (result.exitCode !== 0) {
     // Always name the repository. A bare "fatal: not a valid object name: 'X'"
     // reads as a ref-resolution bug when the real cause is that git ran in a
@@ -119,6 +166,7 @@ export async function createGitWorktree({
     const stderr = result.stderr.toString().trim()
     throw new Error(`${stderr || 'failed to create git worktree'} (in ${repoPath})`)
   }
+  return forkRef
 }
 
 // Force-delete a local branch. Returns false (without throwing) when git
@@ -158,7 +206,7 @@ export async function removeGitWorktree({
   force: boolean
 }): Promise<void> {
   if (!isInsideAimuxWorktreeRoot(targetPath)) {
-    throw new Error(`refusing to delete worktree outside Aimux temp root: ${targetPath}`)
+    throw new Error(`refusing to delete worktree outside Aimux worktree root: ${targetPath}`)
   }
   const result = force
     ? await $`git -C ${repoPath} worktree remove --force ${targetPath}`.quiet().nothrow()

package/src/input/modes/types.ts

@@ -114,6 +114,7 @@ export type SideEffect =
   | { type: 'run-setup' }
   | { type: 'stop-setup' }
   | { type: 'configure-setup-script'; projectId?: string }
+  | { type: 'set-project-default-base-ref'; projectId: string; baseRef: 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. */

package/src/platform/play-sound.ts

@@ -141,6 +141,7 @@ function findPlayer(platform: string): string | null {
 }
 
 let lastPlayedAt = 0
+let playing: { kill: () => void } | null = null
 
 /**
  * Whether enough time has passed since the last sound. Separate from the play
@@ -151,16 +152,17 @@ export function shouldPlayNow(now: number, previous: number): boolean {
 }
 
 /**
- * Play a sound file. Returns whether a player was actually spawned, which is
- * what the settings screen's "Test sound" row reports.
+ * Play a sound file. Returns false only when nothing could play at all — a
+ * missing player or a failed spawn — which is what the settings screen's "Test
+ * sound" row reports. A throttled call is not a failure.
+ *
+ * The throttle covers every caller, the test row included: held down, its key
+ * repeats tens of times a second, and one live player per press is enough to
+ * take CoreAudio down with it.
  */
-export function playSoundFile(
-  path: string,
-  options?: { ignoreThrottle?: boolean; volume?: number }
-): boolean {
+export function playSoundFile(path: string, options?: { volume?: number }): boolean {
   const now = Date.now()
-  const throttled = options?.ignoreThrottle !== true
-  if (throttled && !shouldPlayNow(now, lastPlayedAt)) return false
+  if (!shouldPlayNow(now, lastPlayedAt)) return true
   const platform = process.platform
   const bin = findPlayer(platform)
   if (bin == null) {
@@ -169,10 +171,11 @@ export function playSoundFile(
   }
   const argv = soundPlayerArgv(platform, bin, path, options?.volume ?? DEFAULT_VOLUME)
   try {
-    Bun.spawn(argv, { stderr: 'ignore', stdin: 'ignore', stdout: 'ignore' })
-    // A test press does not start the window: it would swallow a real
-    // notification arriving in the next few hundred milliseconds.
-    if (throttled) lastPlayedAt = now
+    // Cut the previous one rather than layer on top of it. Players come and go
+    // on their own, so killing an already-exited one has to be harmless.
+    playing?.kill()
+    playing = Bun.spawn(argv, { stderr: 'ignore', stdin: 'ignore', stdout: 'ignore' })
+    lastPlayedAt = now
     return true
   } catch (error) {
     logDebug('platform.playSound.error', {

package/src/platform/worktree-paths.ts

@@ -2,12 +2,23 @@ import { createHash } from 'node:crypto'
 import { lstat, mkdir, realpath, rmdir } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
 
-const DEFAULT_WORKTREE_ROOT = '/tmp/aimux-wt'
+// Worktrees hold uncommitted work, so they live in the XDG data dir, not /tmp:
+// a reboot clears /tmp on macOS and on most Linux distros, and took the work
+// with it. The old root stays recognized (never generated) so worktrees created
+// before this change are still classified and deleted as aimux-managed.
+const LEGACY_WORKTREE_ROOT = '/tmp/aimux-wt'
 const MAX_SLUG_LENGTH = 24
 
+function defaultWorktreeRoot(): string {
+  const xdgData = process.env.XDG_DATA_HOME
+  const base =
+    xdgData != null && xdgData !== '' ? xdgData : join(process.env.HOME ?? '.', '.local', 'share')
+  return join(base, 'aimux', 'worktrees')
+}
+
 export function getAimuxWorktreeRoot(): string {
   const root = process.env.AIMUX_WORKTREE_ROOT
-  return root != null && root !== '' ? root : DEFAULT_WORKTREE_ROOT
+  return root != null && root !== '' ? root : defaultWorktreeRoot()
 }
 
 export function sanitizePathSegment(input: string, maxLength = MAX_SLUG_LENGTH): string {
@@ -42,9 +53,10 @@ export function makeWorktreePath({
 
 export function isInsideAimuxWorktreeRoot(path: string): boolean {
   const normalizeTmp = (value: string) => value.replace(/^\/private\/tmp(?=\/|$)/, '/tmp')
-  const root = `${normalizeTmp(resolve(getAimuxWorktreeRoot()))}/`
   const target = `${normalizeTmp(resolve(path))}/`
-  return target.startsWith(root)
+  return [getAimuxWorktreeRoot(), LEGACY_WORKTREE_ROOT].some((root) =>
+    target.startsWith(`${normalizeTmp(resolve(root))}/`)
+  )
 }
 
 export async function ensureAimuxWorktreeRoot(): Promise<string> {
@@ -80,13 +92,13 @@ export async function pruneEmptyWorktreeParent(worktreePath: string): Promise<vo
 export async function assertSafeAimuxWorktreePath(path: string): Promise<void> {
   const root = await ensureAimuxWorktreeRoot()
   if (!isInsideAimuxWorktreeRoot(path)) {
-    throw new Error(`refusing worktree path outside Aimux temp root: ${path}`)
+    throw new Error(`refusing worktree path outside Aimux worktree root: ${path}`)
   }
   // Create the repo-scoped parent (<root>/r-<hash>) before resolving it: git
   // worktree add does not create intermediate dirs, and realpath() would throw
   // ENOENT on the first worktree for a repo. mkdir(recursive) leaves an
   // existing symlink in place, so the realpath check below still catches an
-  // escape out of the temp root.
+  // escape out of the worktree root.
   const parent = resolve(path, '..')
   await mkdir(parent, { recursive: true })
   const realRoot = await realpath(root)

package/src/settings/flags.ts

@@ -0,0 +1,15 @@
+import { loadConfig } from '../config'
+import { FETCH_BASE } from './sections/git'
+
+/**
+ * Settings read outside the screen, off the file rather than the store.
+ *
+ * `live.ts` is the same read side for the running TUI, through hooks over the
+ * hydrated store. These have to answer where there is no store: the CLI never
+ * hydrates one, and a setting only the TUI honours is a setting that lies.
+ */
+
+/** Whether a new workspace forks from the base as pushed, or as last pulled. */
+export function shouldRefreshBase(): boolean {
+  return loadConfig().settings?.[FETCH_BASE] !== false
+}

package/src/settings/sections/git.ts

@@ -5,6 +5,8 @@ import type { SettingSection, SettingValue } from '../types'
 
 import { dispatchGlobal, runSideEffectGlobal } from '../../state/dispatch-ref'
 
+export const FETCH_BASE = 'git.fetchBase'
+
 function isFileListMode(value: SettingValue): value is GitFileListMode {
   return value === 'tree' || value === 'flat'
 }
@@ -81,6 +83,16 @@ export const GIT_SECTION: SettingSection = {
       step: 1,
       storage: 'settings',
     },
+    {
+      // No `apply`: `shouldRefreshBase` reads this off the file, so the CLI —
+      // where this screen never hydrates — honours it too.
+      description: 'Fetch the base branch before forking from it. Off forks from your local copy.',
+      fallback: true,
+      id: FETCH_BASE,
+      kind: 'toggle',
+      label: 'Refresh the base branch',
+      storage: 'settings',
+    },
     {
       apply: (value) => setMultiRepoConfig({ ...getMultiRepoConfig(), enabled: value === true }),
       description: 'Aggregate the status of git repos nested under the project.',

package/src/settings/sections/index.ts

@@ -13,6 +13,7 @@ import { LAYOUT_SECTION } from './layout'
 import { NOTIFICATIONS_SECTION } from './notifications'
 import { SETUP_SECTION } from './setup'
 import { STATUS_BAR_SECTION } from './status-bar'
+import { WORKSPACE_SECTION } from './workspace'
 
 /**
  * Every section, in the order the screen lists them. Adding a setting is one
@@ -24,6 +25,7 @@ export const SETTING_SECTIONS: readonly SettingSection[] = [
   AUTOMATION_SECTION,
   NOTIFICATIONS_SECTION,
   SETUP_SECTION,
+  WORKSPACE_SECTION,
   GIT_SECTION,
   COMMANDS_SECTION,
   EDITOR_SECTION,

package/src/settings/sections/notifications.ts

@@ -45,10 +45,10 @@ function selectedVolume(): number {
  * user has set the row to `off`, which is what makes it safe to call on every
  * status edge.
  */
-export function playNotificationSound(options?: { ignoreThrottle?: boolean }): boolean {
+export function playNotificationSound(): boolean {
   const path = resolveSoundPath(selectedSoundId())
   if (path == null) return false
-  return playSoundFile(path, { ...options, volume: selectedVolume() })
+  return playSoundFile(path, { volume: selectedVolume() })
 }
 
 export const NOTIFICATIONS_SECTION: SettingSection = {
@@ -89,7 +89,7 @@ export const NOTIFICATIONS_SECTION: SettingSection = {
           toast.info('Notification sound is off')
           return
         }
-        if (!playNotificationSound({ ignoreThrottle: true })) {
+        if (!playNotificationSound()) {
           toast.error('Could not play that sound — no audio player found')
         }
       },

package/src/settings/sections/workspace.ts

@@ -0,0 +1,44 @@
+import type { ProjectRecord } from '../../state/types'
+import type { SettingRow, SettingSection } from '../types'
+
+import { runSideEffectGlobal } from '../../state/dispatch-ref'
+
+const BASE_REF_ROW_PREFIX = 'workspace.defaultBaseRef.'
+
+/**
+ * One row per project, over `defaultBaseRef` on its catalog record.
+ *
+ * Per project rather than global because the convention belongs to the repo:
+ * one clone branches off `develop`, the next off `main`, and a single value
+ * would be wrong for every repo but one. Left empty it follows whatever the
+ * repo declares as its default branch, which is the right answer most of the
+ * time and the reason this is a row and not a prompt.
+ */
+function defaultBaseRefRow(project: ProjectRecord): SettingRow {
+  return {
+    description: "Branch new workspaces fork from. Empty follows the repo's own default.",
+    id: `${BASE_REF_ROW_PREFIX}${project.id}`,
+    kind: 'text',
+    label: project.name,
+    placeholder: "the repo's default",
+    // Read through the live state, not the record this row was built from: the
+    // screen rebuilds its rows from the same list it just wrote to.
+    read: (ctx) =>
+      ctx.state.projects.find((entry) => entry.id === project.id)?.defaultBaseRef ?? '',
+    storage: 'app',
+    write: (value) =>
+      runSideEffectGlobal({
+        baseRef: String(value),
+        projectId: project.id,
+        type: 'set-project-default-base-ref',
+      }),
+  }
+}
+
+export const WORKSPACE_SECTION: SettingSection = {
+  id: 'workspace',
+  label: 'Workspaces',
+  rowCount: (projects) => projects.length,
+  rows: (projects: readonly ProjectRecord[]) =>
+    projects.map((project) => defaultBaseRefRow(project)),
+}

package/src/state/types.ts

@@ -217,6 +217,14 @@ export interface ProjectRecord {
   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
 }
 
 export interface ProjectBarState {

package/src/state/validation.ts

@@ -180,7 +180,8 @@ export function isProjectRecord(value: unknown): value is ProjectRecord {
     (value.projectSnapshot === undefined || isProjectSnapshotV1(value.projectSnapshot)) &&
     (value.workspaces === undefined ||
       (Array.isArray(value.workspaces) && value.workspaces.every(isWorkspaceRecord))) &&
-    (value.activeWorkspaceId === undefined || isString(value.activeWorkspaceId))
+    (value.activeWorkspaceId === undefined || isString(value.activeWorkspaceId)) &&
+    (value.defaultBaseRef === undefined || isString(value.defaultBaseRef))
   )
 }