@brimveyn/aimux 1.19.6 → 1.20.1

package/src/cli/commands/worktree/remove.ts

@@ -1,7 +1,10 @@
 import type { CliCommand } from '../../registry'
 
 import { removeGitWorktree } from '../../../git/worktree'
-import { IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS } from '../../../ipc/protocol'
+import {
+  IPC_CAPABILITY_LIST_TABS,
+  IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS,
+} from '../../../ipc/protocol'
 import { SHARED_FLAGS } from '../../flags'
 import { EXIT_OK, writeJson } from '../../output'
 
@@ -36,20 +39,37 @@ export const worktreeRemove: CliCommand = {
       throw new Error('workspace has no primary worktree — cannot resolve repoRoot for git remove')
     }
 
-    // Git side first — matches the UI's discipline in side-effects.ts. If
-    // git refuses (dirty, uncommitted changes) the catalog stays intact.
-    await removeGitWorktree({ force, repoPath: primary.repoRoot, targetPath: worktree.path })
-
     const daemon = await ctx.getDaemon()
     if (!daemon.hasCapability(IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS)) {
       throw new Error(
         'daemon predates worktreeLifecycleEvents capability — restart aimux to pick up the new daemon'
       )
     }
-    await daemon.expectOk('removeWorktreeRecord', {
-      sessionId: workspace.id,
-      worktreeId: worktree.id,
-    })
+    if (daemon.hasCapability(IPC_CAPABILITY_LIST_TABS)) {
+      const live = (await daemon.listTabs(workspace.id)).tabs.filter(
+        (tab) => tab.worktreeId === worktree.id
+      )
+      if (live.length > 0) {
+        throw new Error(
+          `refusing to remove worktree with live tabs: ${live.map((tab) => tab.id).join(', ')}`
+        )
+      }
+    }
+
+    // All capability and liveness checks happen before touching git. If git
+    // refuses a dirty worktree the catalog remains unchanged.
+    await removeGitWorktree({ force, repoPath: primary.repoRoot, targetPath: worktree.path })
+    try {
+      await daemon.expectOk('removeWorktreeRecord', {
+        sessionId: workspace.id,
+        worktreeId: worktree.id,
+      })
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      throw new Error(
+        `worktree removed from git but catalog reconciliation failed for ${worktree.id}: ${message}`
+      )
+    }
 
     writeJson({ id: worktree.id, name: worktree.name, path: worktree.path })
     return EXIT_OK

package/src/cli/index.ts

@@ -64,9 +64,10 @@ function formatFlagLine(flag: FlagSpec): string {
 function printHelp(): void {
   process.stdout.write(
     [
-      'aimux CLI control plane — drive workspaces, worktrees, and tabs from scripts.',
+      'aimux — terminal multiplexer and agent-friendly control plane.',
       '',
       'Usage:',
+      '  aimux                                      Start the interactive TUI',
       '  aimux <group> <verb> [flags] [args]',
       '  aimux <group> --help                        List verbs in a group',
       '  aimux <group> <verb> --help                 Show flags/args for a verb',
@@ -99,15 +100,12 @@ function printHelp(): void {
       'Env:',
       '  AIMUX_PROFILE                  Runtime profile (state dir, socket paths); --profile overrides.',
       '',
-      'Agent recipes:',
-      '  # spawn Claude in a new tab, wait until it idles, snapshot the screen',
-      '  TAB=$(aimux tab create --assistant claude --title fixup | jq -r .tabId)',
-      '  aimux tab send "$TAB" "explain this repo" --enter',
-      '  aimux tab wait "$TAB" --status idle --timeout 60000',
-      '  aimux tab snapshot "$TAB" --tail 40 --format text',
+      'Agent recipe:',
+      '  # create an isolated named worker, dispatch, and await one structured outcome',
+      '  aimux worker run --name fixup --assistant claude "explain this repo"',
       '',
-      '  # stream renders as NDJSON (one event per line)',
-      '  aimux tab tail "$TAB" --rate-limit-ms 100 --follow-status',
+      'Maintenance:',
+      '  aimux doctor | update | restart-daemon | restart-terminal-manager | version',
       '',
     ].join('\n')
   )
@@ -201,6 +199,11 @@ export async function runCli(argv: readonly string[]): Promise<number> {
     if (error instanceof CliUsageError) {
       writeError(error.message)
       writeError(`usage: aimux ${command.group} ${command.verb}`)
+      writeJson({
+        command: `${command.group} ${command.verb}`,
+        error: error.message,
+        kind: 'usage-error',
+      })
       return EXIT_USAGE
     }
     throw error
@@ -241,6 +244,15 @@ export async function runCli(argv: readonly string[]): Promise<number> {
     return code
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
+    if (error instanceof CliUsageError) {
+      writeError(message)
+      writeJson({
+        command: `${command.group} ${command.verb}`,
+        error: message,
+        kind: 'usage-error',
+      })
+      return EXIT_USAGE
+    }
     // Classify by error type, not by string-sniffing the message: a runtime
     // error whose message happens to include "socket" (e.g. daemon reply
     // "socket write failed for tab X") must not masquerade as

package/src/cli/registry.ts

@@ -11,6 +11,12 @@ import { tabSend } from './commands/tab/send'
 import { tabSnapshot } from './commands/tab/snapshot'
 import { tabTail } from './commands/tab/tail'
 import { tabWait } from './commands/tab/wait'
+import { workerAwait } from './commands/worker/await'
+import { workerDoctor } from './commands/worker/doctor'
+import { workerList } from './commands/worker/list'
+import { workerPrompt } from './commands/worker/prompt'
+import { workerRun } from './commands/worker/run'
+import { workerStop } from './commands/worker/stop'
 import { workspaceClose } from './commands/workspace/close'
 import { workspaceCreate } from './commands/workspace/create'
 import { workspaceList } from './commands/workspace/list'
@@ -48,6 +54,12 @@ export const COMMANDS: readonly CliCommand[] = [
   worktreeList,
   worktreeCreate,
   worktreeRemove,
+  workerRun,
+  workerPrompt,
+  workerAwait,
+  workerList,
+  workerStop,
+  workerDoctor,
 ]
 
 export function resolveCommand(group: string, verb: string): CliCommand | null {

package/src/daemon/daemon.ts

@@ -3,8 +3,12 @@ import { connect, createServer, type Socket } from 'node:net'
 
 import type { AssistantId, TabSession, TabStatus, TerminalSnapshot } from '../state/types'
 
+import { version as APP_VERSION } from '../../package.json'
+import { AutoRenameCoordinator, initialAutoRenameStatus } from '../auto-rename/coordinator'
+import { loadUserConfig } from '../config/loader'
 import { logDebug } from '../debug/input-log'
 import { type ClaudeHookServer, startClaudeHookServer } from '../integrations/claude-hook-server'
+import { MANAGER_CAPABILITY_WORKER_METADATA } from '../ipc/manager-protocol'
 import {
   type ClientRequest,
   encodeMessage,
@@ -70,6 +74,8 @@ export interface DaemonTabEntry {
   title?: string
   status?: TabStatus
   worktreeId?: string
+  workerName?: string
+  autoRenameStatus?: 'eligible' | 'attempted'
 }
 
 /**
@@ -91,24 +97,46 @@ export function mergeTabRegistryEntry(
   command: string,
   initialViewport: TerminalSnapshot | undefined,
   allocateSeq: () => number,
-  metadata?: { title?: string; status?: TabStatus; worktreeId?: string }
+  metadata?: {
+    title?: string
+    status?: TabStatus
+    worktreeId?: string
+    workerName?: string
+    autoRenameStatus?: 'eligible' | 'attempted'
+  }
 ): DaemonTabEntry {
   const existing = registry.get(tabId)
   const viewport = existing?.viewport ?? initialViewport
+  const preserveAttemptedMetadata = existing?.autoRenameStatus === 'attempted'
   const entry: DaemonTabEntry = {
     assistant,
+    autoRenameStatus: preserveAttemptedMetadata
+      ? 'attempted'
+      : (metadata?.autoRenameStatus ?? existing?.autoRenameStatus),
     command,
     sessionId,
     status: metadata?.status ?? existing?.status,
-    title: metadata?.title ?? existing?.title,
+    title: preserveAttemptedMetadata ? existing.title : (metadata?.title ?? existing?.title),
     viewport,
     viewportSeq: existing?.viewportSeq ?? (viewport ? allocateSeq() : 0),
+    workerName: metadata?.workerName ?? existing?.workerName,
     worktreeId: metadata?.worktreeId ?? existing?.worktreeId,
   }
   registry.set(tabId, entry)
   return entry
 }
 
+export function findWorkerNameConflict(
+  registry: ReadonlyMap<string, DaemonTabEntry>,
+  sessionId: string,
+  workerName: string
+): string | undefined {
+  for (const [tabId, entry] of registry) {
+    if (entry.sessionId === sessionId && entry.workerName === workerName) return tabId
+  }
+  return undefined
+}
+
 /**
  * Turn-complete settle window for the status loop, overridable via
  * `AIMUX_TURN_SETTLE_MS` for slow/loaded machines. Falls back to the loop's
@@ -193,6 +221,7 @@ async function ensureTerminalManagerReady(manager: TerminalManagerClient): Promi
 }
 
 export async function runDaemon(): Promise<void> {
+  const resolvedConfig = await loadUserConfig()
   const socketPath = getIpcDaemonSocketPath()
   // A handoff file means we were spawned to take over from a predecessor
   // daemon that already drained and renamed its socket away. Consume the
@@ -247,8 +276,14 @@ export async function runDaemon(): Promise<void> {
     assistant: AssistantId,
     command: string,
     initialViewport?: TerminalSnapshot,
-    metadata?: { title?: string; status?: TabStatus; worktreeId?: string }
-  ): void => {
+    metadata?: {
+      title?: string
+      status?: TabStatus
+      worktreeId?: string
+      workerName?: string
+      autoRenameStatus?: 'eligible' | 'attempted'
+    }
+  ): DaemonTabEntry => {
     const before = tabRegistry.get(tabId)
     const entry = mergeTabRegistryEntry(
       tabRegistry,
@@ -270,6 +305,7 @@ export async function runDaemon(): Promise<void> {
       sessionId,
       tabId,
     })
+    return entry
   }
 
   const broadcastAll = (event: ServerEvent): void => {
@@ -315,6 +351,45 @@ export async function runDaemon(): Promise<void> {
     }
   }
 
+  const applyTabMetadata = (
+    tabId: string,
+    patch: { title?: string; autoRenameStatus?: 'eligible' | 'attempted' }
+  ): void => {
+    const entry = tabRegistry.get(tabId)
+    if (!entry) return
+    if (patch.title !== undefined) entry.title = patch.title
+    if (patch.autoRenameStatus !== undefined) entry.autoRenameStatus = patch.autoRenameStatus
+    void (async () => {
+      try {
+        await manager.updateTabMetadata(entry.sessionId, tabId, patch)
+      } catch (error) {
+        logDebug('daemon.tabMetadata.managerFailed', {
+          error: error instanceof Error ? error.message : String(error),
+          tabId,
+        })
+      }
+    })()
+    broadcastForSessionVersioned(entry.sessionId, 14, {
+      payload: { ...patch, sessionId: entry.sessionId, tabId },
+      type: 'tabMetadataUpdated',
+    })
+  }
+
+  const autoRename = new AutoRenameCoordinator({
+    config: resolvedConfig.autoRename,
+    getTab: (tabId) => {
+      const entry = tabRegistry.get(tabId)
+      if (!entry) return
+      return {
+        assistant: entry.assistant,
+        autoRenameStatus: entry.autoRenameStatus,
+        id: tabId,
+        title: entry.title ?? '',
+      }
+    },
+    updateTab: applyTabMetadata,
+  })
+
   // Count UI attachers so workspace/worktree handlers can decide whether to
   // relay via broadcast (UI attached → its reducer owns the write) or mutate
   // the catalog directly. A "UI attacher" here is any non-thin attach — thin
@@ -352,6 +427,7 @@ export async function runDaemon(): Promise<void> {
   manager.on('exit', (sessionId, tabId, exitCode) => {
     logDebug('daemon.manager.exit', { exitCode, sessionId, tabId })
     tabRegistry.delete(tabId)
+    autoRename.unregister(tabId)
     if (sessionActiveTabIds.get(sessionId) === tabId) {
       sessionActiveTabIds.set(sessionId, null)
     }
@@ -530,7 +606,9 @@ export async function runDaemon(): Promise<void> {
                   send(socket, {
                     id: message.id,
                     payload: {
+                      appVersion: APP_VERSION,
                       capabilities: [...IPC_PROTOCOL_CAPABILITIES],
+                      managerCapabilities: [...manager.getCapabilities()],
                       ...(managerSelectedVersion !== null && { managerSelectedVersion }),
                       maxVersion: IPC_PROTOCOL_VERSION,
                       minVersion: IPC_PROTOCOL_MIN_VERSION,
@@ -611,14 +689,26 @@ export async function runDaemon(): Promise<void> {
                   })
                   sessionActiveTabIds.set(message.payload.sessionId, attachResult.activeTabId)
                   for (const tab of attachResult.tabs) {
-                    rememberTab(
+                    const remembered = rememberTab(
                       message.payload.sessionId,
                       tab.id,
                       tab.assistant,
                       tab.command,
                       tab.viewport,
-                      { status: tab.status, title: tab.title, worktreeId: tab.worktreeId }
+                      {
+                        autoRenameStatus: tab.autoRenameStatus,
+                        status: tab.status,
+                        title: tab.title,
+                        workerName: tab.workerName,
+                        worktreeId: tab.worktreeId,
+                      }
                     )
+                    autoRename.register({
+                      assistant: remembered.assistant,
+                      autoRenameStatus: remembered.autoRenameStatus,
+                      id: tab.id,
+                      title: remembered.title ?? tab.title,
+                    })
                   }
                   // Classify synchronously BEFORE sending attachResult so
                   // each tab's activity and the full session-status snapshot
@@ -637,10 +727,16 @@ export async function runDaemon(): Promise<void> {
                     })),
                   })
                   statusLoop.classifyNow(message.payload.sessionId, tabsForLoop)
-                  const tabsWithActivity = attachResult.tabs.map((tab) => ({
-                    ...tab,
-                    activity: statusLoop.getTabStatus(tab.id) ?? tab.activity,
-                  }))
+                  const tabsWithActivity = attachResult.tabs.map((tab) => {
+                    const metadata = tabRegistry.get(tab.id)
+                    return {
+                      ...tab,
+                      activity: statusLoop.getTabStatus(tab.id) ?? tab.activity,
+                      autoRenameStatus: metadata?.autoRenameStatus ?? tab.autoRenameStatus,
+                      title: metadata?.title ?? tab.title,
+                      workerName: metadata?.workerName ?? tab.workerName,
+                    }
+                  })
                   const initialSessionStatuses = statusLoop.snapshotSessions()
                   logDebug('daemon.attach.replay', {
                     sessionId: message.payload.sessionId,
@@ -667,6 +763,23 @@ export async function runDaemon(): Promise<void> {
                 case 'createTab': {
                   const sessionId = requireSession(socket, attachedSessions)
                   requireNegotiatedVersion(socket, negotiatedVersions)
+                  if (message.payload.workerName !== undefined) {
+                    if (!manager.hasCapability(MANAGER_CAPABILITY_WORKER_METADATA)) {
+                      throw new Error(
+                        'the running terminal manager does not support worker metadata; restart aimux before creating named workers'
+                      )
+                    }
+                    const conflictTabId = findWorkerNameConflict(
+                      tabRegistry,
+                      sessionId,
+                      message.payload.workerName
+                    )
+                    if (conflictTabId !== undefined) {
+                      throw new Error(
+                        `worker name already exists in this workspace: ${message.payload.workerName} (${conflictTabId})`
+                      )
+                    }
+                  }
                   // Capability `createTabSizeFallback`: cols/rows = 0 means
                   // "use the session's last attached dimensions". Headless
                   // CLIs don't have a viewport of their own, so this lets
@@ -699,6 +812,11 @@ export async function runDaemon(): Promise<void> {
                     message.payload.command,
                     ...(message.payload.args ?? []),
                   ].join(' ')
+                  const autoRenameStatus = initialAutoRenameStatus(
+                    resolvedConfig.autoRename,
+                    message.payload.assistant,
+                    message.payload.autoRenameCandidate === true
+                  )
                   rememberTab(
                     sessionId,
                     message.payload.tabId,
@@ -706,8 +824,10 @@ export async function runDaemon(): Promise<void> {
                     fullCommand,
                     undefined,
                     {
+                      autoRenameStatus,
                       status: 'starting',
                       title: message.payload.title,
+                      workerName: message.payload.workerName,
                       worktreeId: message.payload.worktreeId,
                     }
                   )
@@ -719,7 +839,25 @@ export async function runDaemon(): Promise<void> {
                   // even on PTYs that outlive this daemon process.
                   const env: Record<string, string> = { AIMUX_PANE_ID: message.payload.tabId }
                   if (hookServer) env.AIMUX_HOOK_URL_FILE = hookUrlFilePath
-                  await manager.createTab({ ...message.payload, cols, env, rows, sessionId })
+                  const { autoRenameCandidate: _autoRenameCandidate, ...managerTabPayload } =
+                    message.payload
+                  try {
+                    await manager.createTab({
+                      ...managerTabPayload,
+                      autoRenameStatus,
+                      cols,
+                      env,
+                      rows,
+                      sessionId,
+                    })
+                  } catch (error) {
+                    // `rememberTab` must happen before the manager call so
+                    // early render events have metadata to merge into. Undo
+                    // that optimistic entry when creation fails, otherwise a
+                    // ghost worker name would block a clean retry.
+                    tabRegistry.delete(message.payload.tabId)
+                    throw error
+                  }
                   sendOk(socket, message.id)
                   // Fan a `tabAdded` event only to peers that negotiated at
                   // least v11 — older parsers throw on unknown message types
@@ -728,18 +866,21 @@ export async function runDaemon(): Promise<void> {
                   const synthesizedTab: TabSession = {
                     activity: 'idle',
                     assistant: message.payload.assistant,
+                    autoRenameStatus,
                     buffer: '',
                     command: fullCommand,
                     id: message.payload.tabId,
                     status: 'starting',
                     terminalModes: createDefaultTerminalModes(),
                     title: message.payload.title,
+                    workerName: message.payload.workerName,
                     worktreeId: message.payload.worktreeId,
                   }
                   broadcastForSessionVersioned(sessionId, 11, {
                     payload: { sessionId, tab: synthesizedTab },
                     type: 'tabAdded',
                   })
+                  autoRename.register(synthesizedTab)
                   logDebug('daemon.request.createTab.success', {
                     sessionId,
                     tabId: message.payload.tabId,
@@ -750,6 +891,21 @@ export async function runDaemon(): Promise<void> {
                   const sessionId = requireSession(socket, attachedSessions)
                   requireNegotiatedVersion(socket, negotiatedVersions)
                   await manager.write(sessionId, message.payload.tabId, message.payload.data)
+                  autoRename.observeWrite(message.payload.tabId, message.payload.data)
+                  sendOk(socket, message.id)
+                  break
+                }
+                case 'renameTab': {
+                  const sessionId = requireSession(socket, attachedSessions)
+                  requireNegotiatedVersion(socket, negotiatedVersions)
+                  if (tabRegistry.get(message.payload.tabId)?.sessionId !== sessionId) {
+                    throw new Error(`Tab not found in attached session: ${message.payload.tabId}`)
+                  }
+                  autoRename.manualRename(message.payload.tabId)
+                  applyTabMetadata(message.payload.tabId, {
+                    autoRenameStatus: 'attempted',
+                    title: message.payload.title.trim(),
+                  })
                   sendOk(socket, message.id)
                   break
                 }
@@ -806,6 +962,7 @@ export async function runDaemon(): Promise<void> {
                   const sessionId = requireSession(socket, attachedSessions)
                   requireNegotiatedVersion(socket, negotiatedVersions)
                   tabRegistry.delete(message.payload.tabId)
+                  autoRename.unregister(message.payload.tabId)
                   if (sessionActiveTabIds.get(sessionId) === message.payload.tabId) {
                     sessionActiveTabIds.set(sessionId, null)
                   }
@@ -832,6 +989,7 @@ export async function runDaemon(): Promise<void> {
                       lastLine: lastNonBlankLine(entry.viewport),
                       status: entry.status ?? 'running',
                       title: entry.title ?? '',
+                      workerName: entry.workerName,
                       worktreeId: entry.worktreeId,
                     })
                   }
@@ -851,7 +1009,10 @@ export async function runDaemon(): Promise<void> {
                   requireNegotiatedVersion(socket, negotiatedVersions)
                   if (sessionId != null && sessionId !== '') {
                     for (const [tabId, entry] of tabRegistry) {
-                      if (entry.sessionId === sessionId) tabRegistry.delete(tabId)
+                      if (entry.sessionId === sessionId) {
+                        autoRename.unregister(tabId)
+                        tabRegistry.delete(tabId)
+                      }
                     }
                     sessionActiveTabIds.delete(sessionId)
                     sessionDimensions.delete(sessionId)

package/src/daemon/session-manager.ts

@@ -67,6 +67,14 @@ export class SessionManager extends EventEmitter<SessionManagerEvents> {
     this.getOrCreateRegistry(sessionId).write(tabId, data)
   }
 
+  updateTabMetadata(
+    sessionId: string,
+    tabId: string,
+    patch: { title?: string; autoRenameStatus?: 'eligible' | 'attempted' }
+  ): void {
+    this.getOrCreateRegistry(sessionId).updateTabMetadata(tabId, patch)
+  }
+
   resize(sessionId: string, cols: number, rows: number, options?: { sync?: boolean }): void {
     this.getOrCreateRegistry(sessionId).resizeAll(cols, rows, options)
   }

package/src/daemon/session-registry.ts

@@ -89,8 +89,12 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
       for (const persisted of snapshot.tabs) {
         const existing = this.tabs.get(persisted.id)
         if (existing) {
-          existing.title = persisted.title
+          if (existing.autoRenameStatus !== 'attempted') {
+            existing.title = persisted.title
+            existing.autoRenameStatus = persisted.autoRenameStatus
+          }
           existing.worktreeId = persisted.worktreeId
+          existing.workerName = persisted.workerName
         }
       }
       if (
@@ -145,12 +149,15 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
     cwd?: string
     /** Extra env injected into the spawned shell. Passed through to the PTY. */
     env?: Record<string, string>
+    autoRenameStatus?: 'eligible' | 'attempted'
     /**
      * Worktree this tab belongs to (for UI grouping). Stored on the
      * TabSession so an attach-time replay surfaces it inside the right
      * worktree column. Optional — tabs not bound to a worktree are valid.
      */
     worktreeId?: string
+    /** Workspace-scoped orchestration handle; does not affect PTY behavior. */
+    workerName?: string
   }): void {
     logDebug('daemon.registry.createSession', {
       args: options.args ?? [],
@@ -164,12 +171,14 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
       this.tabs.set(options.tabId, {
         activity: 'idle',
         assistant: options.assistant,
+        autoRenameStatus: options.autoRenameStatus,
         buffer: '',
         command: [options.command, ...(options.args ?? [])].join(' '),
         id: options.tabId,
         status: 'starting',
         terminalModes: createDefaultTerminalModes(),
         title: options.title,
+        workerName: options.workerName,
         worktreeId: options.worktreeId,
       })
     } else {
@@ -182,13 +191,25 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
       existing.assistant = options.assistant
       existing.title = options.title
       existing.command = [options.command, ...(options.args ?? [])].join(' ')
+      existing.autoRenameStatus = options.autoRenameStatus
       if (options.worktreeId !== undefined) existing.worktreeId = options.worktreeId
+      if (options.workerName !== undefined) existing.workerName = options.workerName
     }
 
     this.activeTabId = options.tabId
     this.ptyManager.createSession(options)
   }
 
+  updateTabMetadata(
+    tabId: string,
+    patch: { title?: string; autoRenameStatus?: 'eligible' | 'attempted' }
+  ): void {
+    const tab = this.tabs.get(tabId)
+    if (!tab) return
+    if (patch.title !== undefined) tab.title = patch.title
+    if (patch.autoRenameStatus !== undefined) tab.autoRenameStatus = patch.autoRenameStatus
+  }
+
   /**
    * Read the in-memory TabSession for a tab. Returned by reference — used by
    * the daemon's `tabAdded` broadcast path to publish the same shape the UI

package/src/git/worktree.ts

@@ -33,6 +33,14 @@ export async function getHeadSha(cwd: string): Promise<string | undefined> {
   return result.text().trim() || undefined
 }
 
+export async function isGitWorktreeDirty(cwd: string): Promise<boolean> {
+  const result = await $`git -C ${cwd} status --porcelain`.quiet().nothrow()
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.toString().trim() || `failed to inspect worktree: ${cwd}`)
+  }
+  return result.text().trim().length > 0
+}
+
 // Local branch names, ordered most-recently-committed first so the likely base
 // surfaces near the top of the picker.
 export async function listLocalBranches(cwd: string): Promise<string[]> {