@brimveyn/aimux 1.23.5 → 1.23.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimveyn/aimux",
-  "version": "1.23.5",
+  "version": "1.23.6",
   "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",
@@ -66,7 +66,7 @@
     "bump:terminal_manager": "bun run scripts/bump-protocol.ts terminal-manager"
   },
   "dependencies": {
-    "@brimveyn/aimux-config": "0.10.6",
+    "@brimveyn/aimux-config": "0.10.7",
     "@opentui/core": "^0.1.90",
     "@opentui/react": "^0.1.90",
     "@resvg/resvg-wasm": "^2.6.2",

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

@@ -65,6 +65,7 @@ import {
   startExistingTab,
 } from './tab-actions'
 import {
+  hibernateWorkspace,
   isForceableWorkspaceDeleteError,
   runDeleteWorkspace,
   runMoveWorkspace,
@@ -390,6 +391,9 @@ export function executeSideEffect(effect: SideEffect, ctx: SideEffectContext): v
       backend.disposeSession(effect.tabId)
       return
     }
+    case 'hibernate-workspace':
+      hibernateWorkspace(ctx, effect.workspaceId)
+      return
     case 'restart-tab':
       restartTabSession(
         backend,

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

@@ -5,6 +5,7 @@ import { logInputDebug } from '../debug/input-log'
 import { createPrefixedId } from '../platform/id'
 import {
   assistantAcceptsPromptArg,
+  buildAssistantSessionArgs,
   getAllAssistantOptions,
   getAssistantOption,
   isCommandAvailable,
@@ -65,6 +66,10 @@ export function createTabSession(
     buffer: '',
     command: customCommand ?? option.command,
     id: createTabId(),
+    // Minted up front, before the CLI has ever run, so the very first spawn can
+    // claim it. Only for assistants that can be told their session id — a shell
+    // tab would just carry a uuid nothing reads.
+    sessionId: option.session ? crypto.randomUUID() : undefined,
     status: 'starting',
     terminalModes: createDefaultTerminalModes(),
     title: option.label,
@@ -75,7 +80,7 @@ export function createTabSession(
 /** Everything `startTabSession` needs from the side-effect context. */
 type StartTabSessionContext = Pick<
   SideEffectContext,
-  'backend' | 'clearStartupGrace' | 'dispatch' | 'startStartupGrace'
+  'backend' | 'clearStartupGrace' | 'dispatch' | 'startStartupGrace' | 'state'
 >
 
 export interface StartTabSessionOptions {
@@ -95,7 +100,7 @@ export interface StartTabSessionOptions {
 
 export function startTabSession(
   ctx: StartTabSessionContext,
-  tab: Pick<TabSession, 'id' | 'assistant' | 'title' | 'command' | 'workspaceId'>,
+  tab: Pick<TabSession, 'id' | 'assistant' | 'title' | 'command' | 'sessionId' | 'workspaceId'>,
   { autoRenameCandidate = true, cols, cwd, extraArgs, rows }: StartTabSessionOptions
 ): void {
   const { backend, clearStartupGrace, dispatch } = ctx
@@ -111,6 +116,12 @@ export function startTabSession(
   ctx.startStartupGrace(tab.id, STARTUP_GRACE_MS)
 
   const { args, executable } = parseCommand(tab.command)
+  // Ahead of `extraArgs` because that is where an initial prompt goes, and the
+  // prompt is positional — a flag after it would be read as part of it.
+  const sessionArgs =
+    tab.sessionId == null
+      ? []
+      : buildAssistantSessionArgs(tab.assistant, ctx.state.customCommands, tab.sessionId)
 
   if (!isCommandAvailable(executable)) {
     clearStartupGrace(tab.id)
@@ -123,7 +134,7 @@ export function startTabSession(
   }
 
   backend.createSession({
-    args: extraArgs ? [...args, ...extraArgs] : args,
+    args: [...args, ...sessionArgs, ...(extraArgs ?? [])],
     assistant: tab.assistant,
     autoRenameCandidate,
     cols,

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

@@ -214,6 +214,50 @@ function disposeWorkspaceTabs(ctx: SideEffectContext, workspaceId: string): void
   }
 }
 
+/**
+ * Put every idle assistant tab in a workspace to sleep: kill the PTY, keep the
+ * frozen screen, resume on focus. The RAM a workspace holds is its assistant
+ * processes — several hundred MB each — and none of it is aimux's own.
+ *
+ * A tab mid-turn is never touched. The lot is deliberately partial rather than
+ * all-or-nothing: one busy tab should not veto the other three, and the toast
+ * says what stayed up so the skip is never silent.
+ *
+ * ponytail: `activity` comes from reading the assistant's screen, so it sees a
+ * turn in progress but not a background task the assistant spawned. Manual-only
+ * for exactly that reason — you know what you left running; a timer would not.
+ */
+export function hibernateWorkspace(ctx: SideEffectContext, workspaceId: string): void {
+  const tabs = ctx.state.tabs.filter(
+    (tab) => tab.workspaceId === workspaceId && tab.role !== 'setup'
+  )
+  const sleepable = tabs.filter(
+    (tab) => (tab.status === 'running' || tab.status === 'starting') && tab.activity === 'idle'
+  )
+  const busy = tabs.filter(
+    (tab) => (tab.status === 'running' || tab.status === 'starting') && tab.activity !== 'idle'
+  )
+
+  for (const tab of sleepable) {
+    ctx.clearIdleTimer(tab.id)
+    ctx.clearStartupGrace(tab.id)
+    ctx.backend.disposeSession(tab.id)
+    ctx.dispatch({ tabId: tab.id, type: 'hibernate-tab' })
+  }
+
+  if (sleepable.length === 0) {
+    toast.info(
+      busy.length > 0 ? `Nothing to hibernate — ${busy.length} tab(s) busy` : 'Nothing to hibernate'
+    )
+    return
+  }
+  toast.success(
+    busy.length > 0
+      ? `Hibernated ${sleepable.length} tab(s), skipped ${busy.length} busy`
+      : `Hibernated ${sleepable.length} tab(s)`
+  )
+}
+
 export async function runDeleteWorkspace(
   ctx: SideEffectContext,
   projectId: string,
@@ -415,7 +459,11 @@ export function removeWorkspaceRecordFromProject(
 }
 
 export function isForceableWorkspaceDeleteError(message: string): boolean {
-  return /active assistant tabs|dirty|uncommitted|modified|untracked|not clean|contains.*changes/i.test(
+  // `force delete` is the marker `removeGitWorktree` appends to every refusal
+  // git raises: matching git's own wording never worked, since a broken worktree
+  // link fatals differently ("is not a working tree", "validation failed", …)
+  // depending on which part of the link broke.
+  return /active assistant tabs|dirty|uncommitted|modified|untracked|not clean|contains.*changes|force delete/i.test(
     message
   )
 }

package/src/app.tsx

@@ -49,7 +49,11 @@ import { ALL_SETTING_ROWS } from './settings/sections'
 import { hydrateSettings } from './settings/settings-store'
 import { aiUsageStore } from './state/ai-usage-store'
 import { appStore, useAppStore } from './state/app-store'
-import { setActiveDispatch, setActiveSideEffectRunner } from './state/dispatch-ref'
+import {
+  runSideEffectGlobal,
+  setActiveDispatch,
+  setActiveSideEffectRunner,
+} from './state/dispatch-ref'
 import { findMostRecentProject, loadProjectCatalog } from './state/project-catalog'
 import { getActiveWorkspacePath } from './state/project-workspaces'
 import { loadSnippetCatalog, mergeConfigSnippets } from './state/snippet-catalog'
@@ -484,6 +488,19 @@ export function App({
 
   useSetupRunner(state, sideEffectCtx)
 
+  // Waking is the counterpart of hibernating, and focus is the only signal it
+  // needs: you looked at the tab, so you want it back. Keyed on the id as well
+  // as the flag so switching between two sleeping tabs wakes the second one.
+  // `restart-tab` already does the whole job — dispose, reset, respawn — and the
+  // respawn now carries `--resume`, so the conversation comes back with it.
+  const wakeTabRef = useRef(activeTab)
+  wakeTabRef.current = activeTab
+  useEffect(() => {
+    const tab = wakeTabRef.current
+    if (tab?.hibernated !== true) return
+    runSideEffectGlobal({ tab, type: 'restart-tab' })
+  }, [activeTab?.id, activeTab?.hibernated])
+
   function processKeyResult(result: KeyResult, modeId: ModeId): void {
     for (const action of result.actions) {
       dispatch(action)

package/src/git/worktree.ts

@@ -1,5 +1,6 @@
 import { $ } from 'bun'
 import { existsSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
 
 import { isInsideAimuxWorktreeRoot } from '../platform/worktree-paths'
 
@@ -227,7 +228,22 @@ export async function removeGitWorktree({
     await $`git -C ${repoPath} worktree prune`.quiet().nothrow()
     return
   }
-  throw new Error(result.stderr.toString().trim() || 'failed to remove git worktree')
+  // git refuses on states it cannot repair — a half-finished removal or a moved
+  // repo leaves a directory git no longer links to ("is not a working tree"),
+  // and no retry ever fixes it, so the row was undeletable forever. Force means
+  // "delete it regardless": finish the job ourselves. The path guard above
+  // already pinned the target inside the Aimux worktree root.
+  if (force) {
+    await rm(targetPath, { force: true, recursive: true })
+    await $`git -C ${repoPath} worktree prune`.quiet().nothrow()
+    return
+  }
+  // Every refusal git can raise here is force-recoverable — the directory lives
+  // under the Aimux worktree root and nothing else owns it — so the message
+  // carries the offer, and `isForceableWorkspaceDeleteError` keys off that
+  // phrase instead of trying to enumerate git's wording.
+  const stderr = result.stderr.toString().trim() || 'failed to remove git worktree'
+  throw new Error(`${stderr} — force delete to remove it anyway`)
 }
 
 export async function listGitWorktrees(repoPath: string): Promise<GitWorktreeInfo[]> {

package/src/input/modes/types.ts

@@ -108,6 +108,7 @@ export type SideEffect =
       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 }

package/src/pty/command-registry.ts

@@ -1,4 +1,5 @@
-import { basename } from 'node:path'
+import { homedir } from 'node:os'
+import { basename, join } from 'node:path'
 
 import type { AssistantId } from '../state/types'
 
@@ -18,12 +19,41 @@ export interface AssistantModelSpec {
   buildEffortArgs?: (effort: string) => string[]
 }
 
+/**
+ * How an assistant names a resumable conversation on the command line. Same
+ * philosophy as `AssistantModelSpec`: the vendor's flag syntax lives on the
+ * assistant definition, not in a resolver.
+ *
+ * Two builders because the two directions are different flags, not one flag
+ * with two meanings — `claude --session-id <uuid>` *claims* an id for a new
+ * conversation and errors with "Session ID … is already in use" if it exists,
+ * while `claude --resume <uuid>` refuses an id that does not. An assistant that
+ * can resume but cannot be told its id up front (codex: `codex resume <id>`,
+ * with no way to fix the id at spawn) has no entry here — its id would have to
+ * be discovered after the fact, which is a different mechanism.
+ */
+export interface AssistantSessionSpec {
+  /** Args that pin a fresh conversation to `sessionId`. */
+  buildSessionArgs: (sessionId: string) => string[]
+  /** Args that reopen the conversation `sessionId` names. */
+  buildResumeArgs: (sessionId: string) => string[]
+  /**
+   * Whether the vendor has a stored conversation under this id. Asking the
+   * filesystem is what lets one spawn path serve both directions: an id with a
+   * transcript resumes, an id without one is claimed fresh. Without it, a tab
+   * you opened and never typed into would resume into "No conversation found"
+   * and exit — and an exiting PTY takes the tab with it.
+   */
+  hasConversation: (sessionId: string) => boolean
+}
+
 export interface AssistantOption {
   id: AssistantId
   label: string
   command: string
   description: string
   model?: AssistantModelSpec
+  session?: AssistantSessionSpec
   /**
    * The CLI starts an interactive session with a positional prompt argument
    * (`claude "…"`, `codex "…"`). When it does, handing the prompt over at spawn
@@ -41,6 +71,23 @@ export interface AssistantOption {
   acceptsPromptArg?: boolean
 }
 
+/**
+ * A machine that has never run `claude` has no `~/.claude/projects`, and
+ * `scanSync` reports a missing cwd by throwing ENOENT rather than yielding
+ * nothing. "No directory" and "directory without this transcript" are the same
+ * answer here — there is no conversation to resume — so the throw is folded back
+ * into the false it should have been. Without this, the very first assistant tab
+ * on a fresh install dies at spawn.
+ */
+function hasClaudeTranscript(sessionId: string): boolean {
+  const cwd = join(homedir(), '.claude', 'projects')
+  try {
+    return new Bun.Glob(`*/${sessionId}.jsonl`).scanSync({ cwd }).next().done !== true
+  } catch {
+    return false
+  }
+}
+
 const DEFAULT_SHELL =
   process.env.SHELL != null && process.env.SHELL !== '' ? process.env.SHELL : 'sh'
 const SHELL_NAME = DEFAULT_SHELL.split('/').pop() ?? 'shell'
@@ -56,6 +103,14 @@ export const ASSISTANT_OPTIONS: AssistantOption[] = [
       buildEffortArgs: (effort) => ['--effort', effort],
       buildModelArgs: (model) => ['--model', model],
     },
+    session: {
+      buildResumeArgs: (sessionId) => ['--resume', sessionId],
+      buildSessionArgs: (sessionId) => ['--session-id', sessionId],
+      // `~/.claude/projects/<cwd-slug>/<uuid>.jsonl`. Globbing the slug away
+      // beats deriving it: the uuid alone is unique, so we never have to model
+      // how the vendor mangles a path into a directory name.
+      hasConversation: (sessionId) => hasClaudeTranscript(sessionId),
+    },
   },
   {
     acceptsPromptArg: true,
@@ -149,11 +204,53 @@ export function assistantAcceptsPromptArg(
 ): boolean {
   const option = getAllAssistantOptions(customCommands).find((entry) => entry.id === assistant)
   if (option?.acceptsPromptArg !== true) return false
-  const custom = customCommands[assistant]
+  return runsVendorProgram(option, customCommands)
+}
+
+/**
+ * Whether the configured command still runs the program the assistant's flags
+ * were written for. Extra flags are fine; a wrapper script is not, because any
+ * flag we append lands on the wrapper rather than the vendor CLI.
+ */
+function runsVendorProgram(
+  option: AssistantOption,
+  customCommands: Record<string, string>
+): boolean {
+  const custom = customCommands[option.id]
   if (custom == null || custom === '') return true
   return basename(parseCommand(custom).executable) === option.command
 }
 
+/**
+ * The args that tie a spawn to `sessionId` — resume when the vendor already has
+ * a conversation under that id, claim it otherwise.
+ *
+ * One function for both directions on purpose: every spawn site (new tab,
+ * split, Ctrl+r, waking a hibernated tab) wants the same thing — "be this
+ * conversation" — and the filesystem, not the call site, is what knows whether
+ * that conversation exists yet. A caller that had to pick would get it wrong
+ * exactly once: on the tab that was opened and never typed into.
+ *
+ * Empty for an assistant with no session support, and for a custom command
+ * that already bakes in its own session flags — doubling `--resume` is an error
+ * the vendor would report at spawn, long after the useful stack is gone.
+ */
+export function buildAssistantSessionArgs(
+  assistant: AssistantId,
+  customCommands: Record<string, string>,
+  sessionId: string
+): string[] {
+  if (sessionId === '') return []
+  const option = getAllAssistantOptions(customCommands).find((entry) => entry.id === assistant)
+  if (!option?.session) return []
+  if (!runsVendorProgram(option, customCommands)) return []
+  const custom = customCommands[assistant] ?? ''
+  if (/(^|\s)(-r|--resume|--session-id|--continue|-c)(\s|$)/.test(custom)) return []
+  return option.session.hasConversation(sessionId)
+    ? option.session.buildResumeArgs(sessionId)
+    : option.session.buildSessionArgs(sessionId)
+}
+
 export function isCommandAvailable(command: string): boolean {
   return Bun.which(command) !== null
 }

package/src/state/actions.ts

@@ -153,6 +153,7 @@ export type TabAction =
   | { 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

package/src/state/project-persistence.ts

@@ -62,6 +62,7 @@ export function serializeProject(state: AppState): ProjectSnapshotV1 {
         errorMessage: tab.errorMessage,
         exitCode: tab.exitCode,
         id: tab.id,
+        sessionId: tab.sessionId,
         status: tab.status === 'disconnected' ? 'running' : tab.status,
         terminalModes: tab.terminalModes,
         title: tab.title,
@@ -129,6 +130,7 @@ export function restoreTabsFromProject(
       errorMessage: tab.errorMessage,
       exitCode: tab.exitCode,
       id: tab.id,
+      sessionId: tab.sessionId,
       status: forceDisconnected ? getDisconnectedStatus(tab.status) : tab.status,
       terminalModes: tab.terminalModes,
       title: tab.title,

package/src/state/reducers/tab-state.ts

@@ -531,6 +531,7 @@ export function reduceTabState(state: AppState, action: AppAction): AppState | n
             buffer: '',
             errorMessage: undefined,
             exitCode: undefined,
+            hibernated: undefined,
             status: 'starting',
             terminalModes: createDefaultTerminalModes(),
             viewport: undefined,
@@ -538,6 +539,20 @@ export function reduceTabState(state: AppState, action: AppAction): AppState | n
         },
         action.tabId
       )
+    case 'hibernate-tab':
+      // Deliberately keeps `buffer` and `viewport`: the frozen screen is the
+      // whole point — you should still see what the assistant last said. That is
+      // the one thing separating this from `reset-tab-project`, which wipes both
+      // because it is about to draw a live PTY over them.
+      return {
+        ...state,
+        tabs: updateTab(state.tabs, action.tabId, (tab) => ({
+          ...tab,
+          activity: 'idle',
+          hibernated: true,
+          status: 'disconnected',
+        })),
+      }
     case 'append-tab-buffer':
       return {
         ...state,

package/src/state/types.ts

@@ -151,6 +151,8 @@ export interface PersistedTabSnapshot {
   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
@@ -246,6 +248,25 @@ export interface TabSession {
   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

package/src/ui/components/layout/sidebar/workspace-row.tsx

@@ -62,6 +62,10 @@ export const WorkspaceRow = memo(function WorkspaceRow({
   // Only the working case animates, so the timer is off for every other row —
   // and off entirely when a sprite is drawing this row instead.
   const spinner = useBusySpinner(activity.working && sprite === null)
+  // A primitive, so the selector stays referentially stable across renders.
+  const hasSleepingTabs = useAppStore((s) =>
+    s.tabs.some((tab) => tab.workspaceId === workspace.id && tab.hibernated === true)
+  )
 
   const handleMouseDown = useCallback(
     (event: OtuiMouseEvent) => {
@@ -102,6 +106,10 @@ export const WorkspaceRow = memo(function WorkspaceRow({
           }),
       ],
     ]
+    entries.push([
+      'Hibernate',
+      () => runSideEffectGlobal({ type: 'hibernate-workspace', workspaceId: workspace.id }),
+    ])
     if (workspace.source !== 'primary') {
       entries.push([
         'Remove workspace',
@@ -184,6 +192,12 @@ export const WorkspaceRow = memo(function WorkspaceRow({
   } else if (activity.done) {
     statusGlyph = '● '
     statusColor = t.success
+  } else if (hasSleepingTabs) {
+    // Last, because anything else is news and this is the absence of it. Without
+    // a marker a hibernated workspace is indistinguishable from an idle one, and
+    // you would not know which rows still hold a running assistant.
+    statusGlyph = 'z '
+    statusColor = t.textMuted
   }
 
   return (

package/src/ui/components/layout/terminal-pane.tsx

@@ -573,7 +573,11 @@ export function TerminalPane({
         // re-introducing the shifted-content / dead-row bug.
         <box position="absolute" bottom={0} left={0} backgroundColor={editorBg}>
           {tab?.status === 'disconnected' ? (
-            <text fg={t.warning}>Restored snapshot. Press Ctrl+r to restart this project.</text>
+            <text fg={t.warning}>
+              {tab.hibernated === true
+                ? 'Hibernated. Resuming…'
+                : 'Restored snapshot. Press Ctrl+r to restart this tab.'}
+            </text>
           ) : null}
           {tab?.errorMessage != null && tab?.errorMessage !== '' ? (
             <text fg={t.error}>{tab.errorMessage}</text>