@brimveyn/aimux 1.19.7 → 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,10 +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,
@@ -72,6 +74,7 @@ export interface DaemonTabEntry {
   title?: string
   status?: TabStatus
   worktreeId?: string
+  workerName?: string
   autoRenameStatus?: 'eligible' | 'attempted'
 }
 
@@ -98,6 +101,7 @@ export function mergeTabRegistryEntry(
     title?: string
     status?: TabStatus
     worktreeId?: string
+    workerName?: string
     autoRenameStatus?: 'eligible' | 'attempted'
   }
 ): DaemonTabEntry {
@@ -115,12 +119,24 @@ export function mergeTabRegistryEntry(
     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
@@ -264,6 +280,7 @@ export async function runDaemon(): Promise<void> {
       title?: string
       status?: TabStatus
       worktreeId?: string
+      workerName?: string
       autoRenameStatus?: 'eligible' | 'attempted'
     }
   ): DaemonTabEntry => {
@@ -589,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,
@@ -680,6 +699,7 @@ export async function runDaemon(): Promise<void> {
                         autoRenameStatus: tab.autoRenameStatus,
                         status: tab.status,
                         title: tab.title,
+                        workerName: tab.workerName,
                         worktreeId: tab.worktreeId,
                       }
                     )
@@ -714,6 +734,7 @@ export async function runDaemon(): Promise<void> {
                       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()
@@ -742,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
@@ -789,6 +827,7 @@ export async function runDaemon(): Promise<void> {
                       autoRenameStatus,
                       status: 'starting',
                       title: message.payload.title,
+                      workerName: message.payload.workerName,
                       worktreeId: message.payload.worktreeId,
                     }
                   )
@@ -802,14 +841,23 @@ export async function runDaemon(): Promise<void> {
                   if (hookServer) env.AIMUX_HOOK_URL_FILE = hookUrlFilePath
                   const { autoRenameCandidate: _autoRenameCandidate, ...managerTabPayload } =
                     message.payload
-                  await manager.createTab({
-                    ...managerTabPayload,
-                    autoRenameStatus,
-                    cols,
-                    env,
-                    rows,
-                    sessionId,
-                  })
+                  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
@@ -825,6 +873,7 @@ export async function runDaemon(): Promise<void> {
                     status: 'starting',
                     terminalModes: createDefaultTerminalModes(),
                     title: message.payload.title,
+                    workerName: message.payload.workerName,
                     worktreeId: message.payload.worktreeId,
                   }
                   broadcastForSessionVersioned(sessionId, 11, {
@@ -940,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,
                     })
                   }

package/src/daemon/session-registry.ts

@@ -94,6 +94,7 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
             existing.autoRenameStatus = persisted.autoRenameStatus
           }
           existing.worktreeId = persisted.worktreeId
+          existing.workerName = persisted.workerName
         }
       }
       if (
@@ -155,6 +156,8 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
      * 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 ?? [],
@@ -175,6 +178,7 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
         status: 'starting',
         terminalModes: createDefaultTerminalModes(),
         title: options.title,
+        workerName: options.workerName,
         worktreeId: options.worktreeId,
       })
     } else {
@@ -189,6 +193,7 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
       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

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[]> {

package/src/index.tsx

@@ -1,9 +1,4 @@
 #!/usr/bin/env bun
-import { createCliRenderer } from '@opentui/core'
-import { createRoot } from '@opentui/react'
-
-import { App } from './app'
-import { loadUserConfig } from './config/loader'
 import { runDaemon } from './daemon/daemon'
 import { getRuntimeProfile } from './daemon/runtime-paths'
 import { logDebug } from './debug/input-log'
@@ -12,8 +7,6 @@ import { runRestartDaemon } from './restart-daemon'
 import { runRestartTerminalManager } from './restart-terminal-manager'
 import { createSessionBackend } from './session-backend/bootstrap'
 import { runTerminalManager } from './terminal-manager/terminal-manager'
-import { BreakingUpdateScreen } from './ui/breaking-update-screen'
-import { setHostPalette } from './ui/host-palette'
 import { runUpdate } from './update'
 
 const command = process.argv[2]
@@ -22,7 +15,7 @@ const runtimeProfile = getRuntimeProfile()
 // CLI control plane (docs/reference/cli.md). Branch BEFORE the UI bootstrap so
 // `aimux tab list` from a non-TTY shell never spins up the React renderer.
 // Dynamic import keeps the CLI code out of the UI's cold-start cost.
-const CLI_GROUPS = new Set(['tab', 'workspace', 'worktree'])
+const CLI_GROUPS = new Set(['tab', 'workspace', 'worktree', 'worker'])
 if (typeof command === 'string' && CLI_GROUPS.has(command)) {
   const { runCli } = await import('./cli')
   process.exit(await runCli(process.argv.slice(2)))
@@ -61,81 +54,25 @@ if (command === 'terminal-manager') {
 }
 
 if (command === '--help' || command === '-h' || command === 'help') {
-  process.stdout.write(
-    [
-      'aimux — terminal multiplexer for AI CLIs',
-      '',
-      'Two surfaces:',
-      '  • Interactive TUI (no args): drive assistants side-by-side in one window.',
-      '  • CLI control plane (`aimux <group> <verb>`): script-friendly, JSON output,',
-      '    designed to be driven by another agent or a shell pipeline.',
-      '',
-      'Interactive',
-      '  aimux                             Start the TUI in the current profile',
-      '',
-      'CLI control plane (JSON on stdout, human-readable errors on stderr)',
-      '  aimux tab       list | create | send | focus | close | snapshot | tail | wait',
-      '  aimux workspace list | show | create | switch | close',
-      '  aimux worktree  list | create | remove',
-      '',
-      '  aimux <group> --help              List verbs in that group',
-      '  aimux <group> <verb> --help       Show flags, args, and exit codes',
-      '',
-      'Common CLI verbs at a glance',
-      '  aimux tab list                                     Enumerate tabs (+ activeTabId)',
-      '  aimux tab create --assistant <id> [--title …]      Spawn claude / codex / opencode / grok / kimi / terminal / …',
-      '  aimux tab send <tabId> [text] [--enter|--keys|--stdin]  Type, chord, or paste into a tab',
-      '  aimux tab focus <tabId>                            Bring a tab to the foreground',
-      '  aimux tab close <tabId>                            Terminate a tab',
-      '  aimux tab snapshot <tabId> [--tail N] [--format …] Capture the screen (json | text)',
-      '  aimux tab tail <tabId> [--follow-status] […]       NDJSON stream of renders / status',
-      '  aimux tab wait <tabId> --status <idle|working|waiting-input>  Block on an activity state',
-      '  aimux workspace show                               Dump the active workspace + worktrees',
-      '  aimux workspace create <name> [--project P] [--switch [--wait]]',
-      '  aimux workspace switch <ws> [--wait --timeout N]   Move the running UI to another workspace',
-      '  aimux worktree create --name <n> [--branch B --base R]',
-      '  aimux worktree remove <id|path> [--force]',
-      '',
-      'Shared flags (accepted by every CLI verb)',
-      '  --workspace <id|name>             Target a specific workspace (default: active)',
-      '  --profile <name>                  Runtime profile (also settable via AIMUX_PROFILE)',
-      '  --json                            Reserved; JSON is always on',
-      '',
-      'Maintenance',
-      '  aimux update                      Update aimux to the latest published version',
-      '  aimux doctor                      Diagnose setup (paths, sockets, PTY, integrations)',
-      '  aimux restart-daemon              Restart the IPC daemon (keeps live workspaces)',
-      '  aimux restart-terminal-manager    Restart terminal-manager (kills live workspaces)',
-      '  aimux --version                   Print the installed version',
-      '',
-      'Exit codes',
-      '  0    success',
-      '  2    usage error (bad flags, unknown command, missing argument)',
-      '  3    runtime error (server replied with error, command failed)',
-      '  4    daemon unreachable (socket missing and autostart failed)',
-      '  124  timeout (tab wait, tab tail --timeout, workspace switch --wait)',
-      '',
-      'Env',
-      '  AIMUX_PROFILE                     Runtime profile (state dir, socket paths)',
-      '',
-      'Recipes for agents',
-      '  # spawn Claude, wait for idle, dump the last 40 non-blank lines',
-      '  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',
-      '',
-      '  # send a control chord (Ctrl-C then Esc) using vim-style notation',
-      '  aimux tab send "$TAB" "<C-c><Esc>" --keys',
-      '',
-      '  # follow a tab as NDJSON, one render (or tabStatus) per line',
-      '  aimux tab tail "$TAB" --rate-limit-ms 100 --follow-status',
-      '',
-    ].join('\n')
-  )
-  process.exit(0)
+  const { runCli } = await import('./cli')
+  process.exit(await runCli([]))
 }
 
+const [
+  { createCliRenderer },
+  { createRoot },
+  { App },
+  { loadUserConfig },
+  { BreakingUpdateScreen },
+  { setHostPalette },
+] = await Promise.all([
+  import('@opentui/core'),
+  import('@opentui/react'),
+  import('./app'),
+  import('./config/loader'),
+  import('./ui/breaking-update-screen'),
+  import('./ui/host-palette'),
+])
 const resolvedConfig = await loadUserConfig()
 
 const renderer = await createCliRenderer({

package/src/ipc/manager-protocol.ts

@@ -35,8 +35,14 @@ import {
 //
 // v9: additive — `tabMetadata` updates titles and auto-rename state without
 // restarting PTYs. Capability-gated; MIN remains at 8.
-export const MANAGER_PROTOCOL_MIN_VERSION = 8
-export const MANAGER_PROTOCOL_VERSION = 9
+//
+// v10: additive — `workerName` persists a workspace-scoped orchestration
+// handle on tabs created through the headless worker facade.
+//
+// v11: breaking release boundary — force a fresh terminal-manager so named
+// worker metadata is guaranteed to survive daemon reattach and process swaps.
+export const MANAGER_PROTOCOL_MIN_VERSION = 11
+export const MANAGER_PROTOCOL_VERSION = 11
 
 /**
  * Capability strings advertised by *this* process in its `helloResult`. New
@@ -48,9 +54,11 @@ export const MANAGER_PROTOCOL_CAPABILITIES: readonly string[] = [
   'setBroadcastEnabled',
   'createTabWorktreeId',
   'tabMetadata',
+  'workerMetadata',
 ]
 
 export const MANAGER_CAPABILITY_TAB_METADATA = 'tabMetadata'
+export const MANAGER_CAPABILITY_WORKER_METADATA = 'workerMetadata'
 
 /**
  * Capability name a daemon must observe on the TM's helloResult before
@@ -125,6 +133,7 @@ export type ManagerRequest =
          * `worktreeId = undefined`.
          */
         worktreeId?: string
+        workerName?: string
         autoRenameStatus?: 'eligible' | 'attempted'
       }
     }
@@ -381,6 +390,10 @@ export function parseManagerRequest(value: unknown): ManagerRequest {
         value.payload.worktreeId === undefined || isString(value.payload.worktreeId),
         'createTab.worktreeId must be a string when present'
       )
+      assert(
+        value.payload.workerName === undefined || isString(value.payload.workerName),
+        'createTab.workerName must be a string when present'
+      )
       assert(
         value.payload.autoRenameStatus === undefined ||
           value.payload.autoRenameStatus === 'eligible' ||

package/src/ipc/protocol.ts

@@ -40,8 +40,14 @@ import { isWorkspaceSnapshotV1, isWorktreeRecord } from '../state/validation'
 //
 // v14: additive — tab metadata synchronization for manual and automatic
 // renames. The new request/event are capability-gated; MIN stays at 10.
-export const IPC_PROTOCOL_MIN_VERSION = 10
-export const IPC_PROTOCOL_VERSION = 14
+//
+// v15: additive — workspace-scoped `workerName` metadata on create, attach,
+// and list results. This powers stable name-or-id orchestration selectors.
+//
+// v16: breaking release boundary — the agent-first worker control plane and
+// its metadata guarantees are now required. Old app/daemon pairs must not mix.
+export const IPC_PROTOCOL_MIN_VERSION = 16
+export const IPC_PROTOCOL_VERSION = 16
 
 /**
  * Capability advertised by a daemon that knows how to drain + handoff its
@@ -106,6 +112,7 @@ export const IPC_CAPABILITY_WORKSPACE_LIFECYCLE = 'workspaceLifecycle'
  * fanout as workspaceLifecycle.
  */
 export const IPC_CAPABILITY_WORKTREE_LIFECYCLE_EVENTS = 'worktreeLifecycleEvents'
+export const IPC_CAPABILITY_WORKER_METADATA = 'workerMetadata'
 
 /**
  * v12 — capability marker for `aimux tab tail`. Functionally it's just a
@@ -167,6 +174,7 @@ export const IPC_PROTOCOL_CAPABILITIES: readonly string[] = [
   IPC_CAPABILITY_QUESTION_EVENTS,
   IPC_CAPABILITY_LIST_TABS_LAST_LINE,
   IPC_CAPABILITY_TAB_METADATA,
+  IPC_CAPABILITY_WORKER_METADATA,
 ]
 
 export interface ProtocolHelloRequest {
@@ -175,6 +183,8 @@ export interface ProtocolHelloRequest {
 }
 
 export interface ProtocolHelloResult {
+  /** aimux package version; absent on older daemons. */
+  appVersion?: string
   minVersion: number
   maxVersion: number
   processVersion: string
@@ -184,6 +194,8 @@ export interface ProtocolHelloResult {
    * not yet advertise capabilities are normalised to `[]` at parse time.
    */
   capabilities: string[]
+  /** Capabilities negotiated with the terminal-manager; absent on older daemons. */
+  managerCapabilities?: string[]
   /**
    * Manager-protocol version currently negotiated between the daemon and
    * its terminal-manager. `undefined` when the daemon has not yet connected
@@ -227,6 +239,7 @@ export interface TabSessionSummary {
   activity?: TabActivity
   command: string
   worktreeId?: string
+  workerName?: string
   /**
    * v13 / capability `listTabsLastLine`. The tab's last non-blank rendered
    * line, trimmed. Present only when the daemon advertises the capability;
@@ -276,6 +289,8 @@ export type ClientRequest =
          * only forwards it to the TM when its own capability is in play.
          */
         worktreeId?: string
+        /** v15 / capability `workerMetadata`: stable workspace-scoped handle. */
+        workerName?: string
         /** True only when the creator did not provide an explicit title. */
         autoRenameCandidate?: boolean
       }
@@ -566,12 +581,14 @@ function isProtocolHelloResult(value: unknown): value is ProtocolHelloResult {
     isFiniteNumber(value.maxVersion) &&
     isFiniteNumber(value.selectedVersion) &&
     isString(value.processVersion) &&
+    (value.appVersion === undefined || isString(value.appVersion)) &&
     // Wire-back-compat: peers that predate the capabilities field omit it
     // entirely. parseServerMessage normalises that to `[]` before the cast
     // so the typed shape stays non-optional.
     (value.capabilities === undefined || isStringArray(value.capabilities)) &&
     // Additive: peers that predate managerSelectedVersion omit it.
-    (value.managerSelectedVersion === undefined || isFiniteNumber(value.managerSelectedVersion))
+    (value.managerSelectedVersion === undefined || isFiniteNumber(value.managerSelectedVersion)) &&
+    (value.managerCapabilities === undefined || isStringArray(value.managerCapabilities))
   )
 }
 
@@ -592,6 +609,7 @@ function isTabSessionSummary(value: unknown): value is TabSessionSummary {
       value.activity === 'idle') &&
     isString(value.command) &&
     (value.worktreeId === undefined || isString(value.worktreeId)) &&
+    (value.workerName === undefined || isString(value.workerName)) &&
     (value.lastLine === undefined || isString(value.lastLine))
   )
 }
@@ -627,6 +645,7 @@ function isTabSession(value: unknown): value is TabSession {
     isString(value.buffer) &&
     isTerminalModeState(value.terminalModes) &&
     isString(value.command) &&
+    (value.workerName === undefined || isString(value.workerName)) &&
     (value.autoRenameStatus === undefined ||
       value.autoRenameStatus === 'eligible' ||
       value.autoRenameStatus === 'attempted') &&
@@ -736,6 +755,10 @@ export function parseClientRequest(value: unknown): ClientRequest {
         value.payload.worktreeId === undefined || isString(value.payload.worktreeId),
         'createTab.worktreeId must be a string when present'
       )
+      assert(
+        value.payload.workerName === undefined || isString(value.payload.workerName),
+        'createTab.workerName must be a string when present'
+      )
       assert(
         value.payload.autoRenameCandidate === undefined ||
           typeof value.payload.autoRenameCandidate === 'boolean',

package/src/state/session-persistence.ts

@@ -59,6 +59,7 @@ export function serializeWorkspace(state: AppState): WorkspaceSnapshotV1 {
       terminalModes: tab.terminalModes,
       title: tab.title,
       viewport: tab.viewport,
+      workerName: tab.workerName,
       worktreeId: tab.worktreeId,
     })),
     version: 1,
@@ -124,6 +125,7 @@ export function restoreTabsFromWorkspace(
       terminalModes: tab.terminalModes,
       title: tab.title,
       viewport: tab.viewport,
+      workerName: tab.workerName,
       worktreeId: tab.worktreeId,
     }))
   return pruneOrphanedTabs(restored, options.validWorktreeIds)