cru-teams 1.0.3 → 1.2.0

package/README.md

@@ -25,6 +25,7 @@ Agent teams let multiple Claude Code instances work together in parallel — cru
 - **Already using tmux?** You're good.
 - **iTerm2?** Use [`tmux -CC`](https://iterm2.com/documentation-tmux-integration.html) for native pane integration.
 - **Ghostty?** Workers still run in tmux (that's how Claude Code spawns agents), but cru mirrors them into native Ghostty splits via [AppleScript](https://ghostty.org/docs/features/applescript) — so you get Ghostty's UI instead of working inside tmux yourself. Requires Ghostty v1.3.0+.
+- **[cmux](https://www.cmux.dev)?** Native support — cru mirrors workers into cmux splits via the cmux CLI socket. Tabs get labeled with ◫ (lead) and ⚡ (workers) for quick identification. Auto-detected when running inside cmux.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cru-teams",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "◫ Manage terminal layouts for Claude Code agent teams",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -21,9 +21,11 @@ const PREFLIGHT: Record<string, string[]> = {
   panes: ['pane-session'],
 }
 
+const pkg = require('../package.json')
+
 Cli.create('cru', {
   description: '◫ Manage pane layouts for Claude Code agent teams',
-  version: '1.0.0',
+  version: pkg.version,
 })
   .use(async (c, next) => {
     const checks = PREFLIGHT[c.command]

package/src/commands/panes.ts

@@ -135,87 +135,186 @@ function runGridGhostty(c) {
   }
 }
 
+const WORKER_COLORS = ['green', 'blue', 'yellow', 'magenta', 'cyan', 'red']
+
+/** Resolve worker names from team config, falling back to "worker-N". */
+function resolveWorkerNames(teamName: string | undefined, count: number): string[] {
+  if (teamName) {
+    try {
+      const config = readTeamConfig(teamName)
+      // Filter out the lead (role=lead or name=main/team-lead) — only want workers
+      const names = (config.members || [])
+        .filter((m: any) => m.role !== 'lead' && m.name !== 'main' && m.name !== 'team-lead')
+        .map((m: any) => m.name)
+      if (names.length >= count) return names.slice(0, count)
+    } catch {}
+  }
+  return Array.from({ length: count }, (_, i) => `worker-${i + 1}`)
+}
+
+/** Apply config overrides from CLI options. */
+function applyConfigOverrides(conf: ReturnType<typeof loadConfig>, options: any): void {
+  if (options['lead-size'] != null) conf.layout.lead.size = options['lead-size']
+  if (options['lead-position']) conf.layout.lead.position = options['lead-position']
+  if (options.fill) conf.layout.grid.fill = options.fill
+  if (options['max-cols'] != null) conf.layout.grid.maxCols = options['max-cols']
+  if (options['max-rows'] != null) conf.layout.grid.maxRows = options['max-rows']
+}
+
+/**
+ * cmux grid: mirror headless tmux workers into cmux splits.
+ *
+ * Same approach as Ghostty: workers spawn in `tmux -L claude-swarm-*`
+ * sessions. We find the swarm, break each pane into its own tmux window,
+ * create cmux splits, and attach each to a view session.
+ */
 function runGridCmux(c) {
+  const {
+    findBestSwarm,
+    getWorkerPanes,
+    mirrorWorkerToCmux,
+    setRemainOnExit,
+  } = require('../lib/mirror')
   const {
     currentSurface,
-    listSurfaces,
-    buildGrid,
     focusSurface,
     closeSurface,
-  } = require('../lib/cmux')
-
-  const conf = loadConfig()
-  if (c.options['lead-size'] != null) conf.layout.lead.size = c.options['lead-size']
-  if (c.options['lead-position']) conf.layout.lead.position = c.options['lead-position']
-  if (c.options.fill) conf.layout.grid.fill = c.options.fill
-  if (c.options['max-cols'] != null) conf.layout.grid.maxCols = c.options['max-cols']
-  if (c.options['max-rows'] != null) conf.layout.grid.maxRows = c.options['max-rows']
+    renameSurface,
+    getSurfaceTitle,
+    notify,
+    setStatus,
+    setProgress,
+    sidebarLog,
+    clearStatus,
+    clearProgress,
+    clearLog,
+    setPhase,
+    clearPhase,
+    spawnProgressWatcher,
+  } = require('../lib/cmux') as typeof import('../lib/cmux')
 
   const teamName = c.args.team
+  const expectedWorkers = c.options.expect
   const leadSurface = currentSurface()
+  const deadline = Date.now() + 60_000
 
-  // If team already has tracked panes, close old workers first
+  // Close previously-tracked workers (never arbitrary surfaces)
   if (teamName) {
     const existing = loadPanes(teamName)
     if (existing?.backend === 'cmux') {
-      for (const w of existing.workers) {
-        closeSurface(w.paneId)
-      }
+      for (const w of existing.workers) closeSurface(w.paneId)
       Bun.sleepSync(300)
     }
   }
 
-  // Count existing non-lead surfaces as workers, or use --expect
-  let workerCount = c.options.expect
-  if (!workerCount) {
-    const surfaces = listSurfaces()
-    workerCount = surfaces.length - 1 // subtract lead
-    if (workerCount < 1) {
-      return c.error({ code: 'NO_WORKERS', message: 'Only one surface — nothing to arrange. Use --expect N to create workers.' })
+  // 1. Find the swarm socket
+  let swarm: { socket: string; session: string } | null = null
+  if (expectedWorkers) {
+    while (Date.now() < deadline) {
+      swarm = findBestSwarm(expectedWorkers)
+      if (swarm) break
+      Bun.sleepSync(200)
     }
+  } else {
+    swarm = findBestSwarm()
   }
 
-  // If --expect is set and we need to create surfaces
-  const surfaces = listSurfaces()
-  const existingWorkerCount = surfaces.length - 1
-  if (c.options.expect && existingWorkerCount < c.options.expect) {
-    // Close existing non-lead surfaces to rebuild from scratch
-    for (const s of surfaces) {
-      if (s.id !== leadSurface) {
-        closeSurface(s.id)
+  if (!swarm) {
+    return c.error({
+      code: 'NO_SWARM',
+      message: 'No claude-swarm tmux session found. Is a Claude Code team running?',
+    })
+  }
+
+  console.log(`  [grid] found swarm: ${swarm.socket}/${swarm.session}`)
+  setRemainOnExit(swarm.socket)
+
+  const label = teamName || 'cru'
+  setStatus('team', label, { icon: 'person.2.fill', color: '#6366f1' })
+  setPhase('spawning', label)
+  sidebarLog('Swarm found, mirroring workers...', 'progress')
+
+  // 2. Incrementally mirror workers into a grid layout
+  const conf = loadConfig()
+  applyConfigOverrides(conf, c.options)
+  const totalExpected = expectedWorkers || 1
+  const { cols } = computeGrid(totalExpected, conf.layout)
+  const mirrored = new Map<string, { cmuxSurface: string; viewSession: string }>()
+  const mirroredSurfaces: string[] = []
+
+  setProgress(0, `0/${totalExpected} workers`)
+
+  while (Date.now() < deadline) {
+    const allWorkers = getWorkerPanes(swarm.socket)
+    const newWorkers = allWorkers.filter((p: string) => !mirrored.has(p))
+
+    for (const paneId of newWorkers) {
+      const idx = mirrored.size
+      const row = Math.floor(idx / cols)
+      const col = idx % cols
+
+      let splitDir: 'right' | 'down'
+      let splitTarget: string
+      if (idx === 0) {
+        splitDir = 'right'
+        splitTarget = leadSurface
+      } else if (row === 0) {
+        splitDir = 'right'
+        splitTarget = mirroredSurfaces[idx - 1]
+      } else {
+        splitDir = 'down'
+        splitTarget = mirroredSurfaces[(row - 1) * cols + col]
       }
-    }
-    Bun.sleepSync(300)
-
-    // Build fresh grid
-    const workerSurfaces = buildGrid(leadSurface, workerCount, conf.layout)
-
-    if (teamName) {
-      savePanes(teamName, {
-        leadPane: leadSurface,
-        windowId: leadSurface,
-        backend: 'cmux',
-        createdAt: Date.now(),
-        workers: workerSurfaces.map((id: string, i: number) => ({
-          name: `worker-${i + 1}`,
-          paneId: id,
-          color: ['green', 'blue', 'yellow', 'magenta', 'cyan', 'red'][i % 6],
-        })),
-      })
+
+      const result = mirrorWorkerToCmux(
+        swarm.socket, swarm.session,
+        paneId, idx, splitTarget, splitDir,
+      )
+      mirrored.set(paneId, result)
+      mirroredSurfaces.push(result.cmuxSurface)
+
+      // Update sidebar progress
+      sidebarLog(`worker-${idx + 1} mirrored`, 'success')
+      setProgress(mirrored.size / totalExpected, `${mirrored.size}/${totalExpected} workers`)
     }
 
-    focusSurface(leadSurface)
+    if (expectedWorkers && mirrored.size >= expectedWorkers) break
 
-    return {
-      applied: true,
-      backend: 'cmux',
-      lead: { position: conf.layout.lead.position, size: `${conf.layout.lead.size}%` },
-      workers: workerSurfaces.length,
+    if (!expectedWorkers && mirrored.size > 0 && newWorkers.length === 0) {
+      Bun.sleepSync(3000)
+      const finalWorkers = getWorkerPanes(swarm.socket)
+      if (finalWorkers.filter((p: string) => !mirrored.has(p)).length === 0) break
+      continue
     }
+
+    Bun.sleepSync(200)
   }
 
-  // Rearrange existing surfaces — just track them
-  const workerSurfaces = surfaces.filter((s: any) => s.id !== leadSurface)
+  if (mirrored.size === 0) {
+    clearProgress()
+    clearStatus('team')
+    clearPhase()
+    return c.error({ code: 'NO_WORKERS', message: 'No worker panes found in swarm.' })
+  }
+
+  // 3. Label surfaces
+  const leadOriginalTitle = getSurfaceTitle(leadSurface)
+  try { renameSurface(leadSurface, `${leadOriginalTitle} (◫ lead @ ${label})`) } catch {}
+
+  const mirrors = [...mirrored.entries()]
+  const names = resolveWorkerNames(teamName, mirrors.length)
+  const workers = mirrors.map(([, m], i) => {
+    try { renameSurface(m.cmuxSurface, `⚡ ${names[i]} @ ${label}`) } catch {}
+    return { name: names[i], paneId: m.cmuxSurface, color: WORKER_COLORS[i % WORKER_COLORS.length] }
+  })
+
+  // 4. Finalize sidebar — clear spawn artifacts, switch to working
+  clearProgress()
+  clearLog()
+  setStatus('team', `${label} (${workers.length} workers)`, { icon: 'person.2.fill', color: '#22c55e' })
+  setPhase('working', label)
+  notify(`◫ ${label}`, `Team ready — ${workers.length} workers in grid`)
+  focusSurface(leadSurface)
 
   if (teamName) {
     savePanes(teamName, {
@@ -223,21 +322,19 @@ function runGridCmux(c) {
       windowId: leadSurface,
       backend: 'cmux',
       createdAt: Date.now(),
-      workers: workerSurfaces.map((s: any, i: number) => ({
-        name: `worker-${i + 1}`,
-        paneId: s.id,
-        color: ['green', 'blue', 'yellow', 'magenta', 'cyan', 'red'][i % 6],
-      })),
+      workers,
+      leadOriginalTitle,
     })
-  }
 
-  focusSurface(leadSurface)
+    // Start background task progress watcher
+    spawnProgressWatcher(teamName)
+  }
 
   return {
     applied: true,
     backend: 'cmux',
-    lead: { position: conf.layout.lead.position, size: `${conf.layout.lead.size}%` },
-    workers: workerSurfaces.length,
+    swarm: `${swarm.socket}/${swarm.session}`,
+    workers: mirrored.size,
   }
 }
 
@@ -253,12 +350,7 @@ function runGrid(c) {
   }
 
   const conf = loadConfig()
-
-  if (c.options['lead-size'] != null) conf.layout.lead.size = c.options['lead-size']
-  if (c.options['lead-position']) conf.layout.lead.position = c.options['lead-position']
-  if (c.options.fill) conf.layout.grid.fill = c.options.fill
-  if (c.options['max-cols'] != null) conf.layout.grid.maxCols = c.options['max-cols']
-  if (c.options['max-rows'] != null) conf.layout.grid.maxRows = c.options['max-rows']
+  applyConfigOverrides(conf, c.options)
 
   const teamName = c.args.team
   let windowId: string | null = null
@@ -399,11 +491,12 @@ function runClose(c) {
   }
 
   if (closed.length === 0 && inCmux()) {
-    // Fallback: close all non-lead cmux surfaces
+    // Fallback: close all non-lead cmux surfaces in the caller's workspace only
     try {
-      const { currentSurface, listAllSurfaceIds, closeSurface } = require('../lib/cmux')
+      const { currentSurface, currentWorkspace, listAllSurfaceIds, closeSurface } = require('../lib/cmux')
       const lead = currentSurface()
-      const allSurfaces = listAllSurfaceIds()
+      const ws = currentWorkspace()
+      const allSurfaces = listAllSurfaceIds(ws)
       for (const id of allSurfaces) {
         if (id !== lead) {
           closeSurface(id)
@@ -439,16 +532,40 @@ function runClose(c) {
     } catch {}
   }
 
+  // Restore lead pane's original title and clear sidebar
+  if (cruPanes?.backend === 'cmux') {
+    const { renameSurface, notify, clearStatus, clearProgress, clearPhase, clearLog } = require('../lib/cmux')
+    if (cruPanes.leadOriginalTitle != null) {
+      try { renameSurface(cruPanes.leadPane, cruPanes.leadOriginalTitle) } catch {}
+    }
+    try { notify(`◫ ${teamName}`, `Team shut down — ${closed.length} workers closed`) } catch {}
+    // Clean slate — remove all cru sidebar state
+    try { clearStatus('team') } catch {}
+    try { clearPhase() } catch {}
+    try { clearProgress() } catch {}
+    try { clearLog() } catch {}
+  }
+
+  // Clean up pane tracking file (team data stays for `cru logs` review)
+  if (teamName && closed.length > 0) {
+    try {
+      const { unlinkSync } = require('node:fs')
+      const { join } = require('node:path')
+      const { teamsDir } = require('../lib/paths')
+      unlinkSync(join(teamsDir(), teamName, 'cru-panes.json'))
+    } catch {}
+  }
+
   return { team: teamName, closed: closed.length, panes: closed }
 }
 
 function runList(c) {
   if (inCmux()) {
-    const { currentSurface, listSurfaces, readScreen } = require('../lib/cmux')
+    const { currentSurface, listSurfaces } = require('../lib/cmux')
     let currentId: string | null = null
     try { currentId = currentSurface() } catch {}
     const surfaces = listSurfaces()
-    const panes = surfaces.map((s: any) => ({
+    const panes = surfaces.map((s: { id: string; index: number }) => ({
       id: s.id,
       index: s.index,
       current: s.id === currentId,

package/src/lib/cmux.ts

@@ -1,12 +1,16 @@
 /**
  * cmux backend — native pane management via the cmux CLI.
  *
- * cmux is a Ghostty-based macOS terminal with vertical tabs,
- * notifications, and a CLI for controlling panes/surfaces via
- * a Unix socket (/tmp/cmux.sock).
+ * cmux is a macOS terminal with a CLI for controlling panes/surfaces
+ * via a Unix socket (/tmp/cmux.sock).
  *
- * Surfaces = individual terminal instances (like tmux panes).
- * Panes    = split containers holding one or more surfaces.
+ * IMPORTANT: All operations pass explicit --surface/--workspace flags
+ * so they work regardless of which tab/surface the user has focused.
+ * identify() prefers the caller's own surface, falling back to focused
+ * only when env vars are stale (e.g. detached scripts).
+ *
+ * Surface refs (surface:N) are monotonic — they don't shift when
+ * other surfaces are created or destroyed, so they're safe to store.
  *
  * Environment variables set by cmux in each terminal:
  *   CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, CMUX_SOCKET_PATH
@@ -17,103 +21,120 @@ import { computeGrid } from './layout'
 import type { LayoutConf } from './tmux'
 
 export interface CmuxSurface {
-  id: string   // e.g. "surface:1"
-  index: number
-}
-
-export interface CmuxSurfaceDetails {
-  id: string
+  id: string   // e.g. "surface:15" — monotonic ref, stable for the session
   index: number
-  type: string
-  focused: boolean
   title: string
+  focused: boolean
 }
 
+// ---------------------------------------------------------------------------
+// Core
+// ---------------------------------------------------------------------------
+
 /** Run a cmux CLI command safely (no shell interpolation). */
 export function cmux(...args: string[]): string {
   return execFileSync('cmux', args, { encoding: 'utf-8', timeout: 10_000 }).trim()
 }
 
-/** Check if we're inside a cmux terminal. */
-export function inCmux(): boolean {
-  return !!process.env.CMUX_WORKSPACE_ID
-}
-
-/** Get the current surface ID (the surface running this process). */
-export function currentSurface(): string {
-  const envSurface = process.env.CMUX_SURFACE_ID
-  if (envSurface) {
-    // cmux identify returns JSON with refs — verify surface is still valid
-    try {
-      const info = JSON.parse(cmux('identify', '--no-caller'))
-      if (info.focused?.surface_ref) {
-        // env var is a UUID; we need the ref format for commands
-        const panels = cmux('list-panels')
-        // Find the line that matches our UUID or is focused
-        const lines = panels.split('\n').filter(Boolean)
-        for (const line of lines) {
-          if (line.includes('[focused]')) {
-            const match = line.match(/^[*\s]*(surface:\d+)/)
-            if (match) return match[1]
-          }
-        }
-      }
-    } catch {}
-  }
-
-  // Fallback: use identify to get caller's surface ref
+/** Check if cmux socket is responding. */
+export function isCmuxAvailable(): boolean {
   try {
-    const info = JSON.parse(cmux('identify'))
-    return info.caller?.surface_ref || 'surface:1'
+    cmux('ping')
+    return true
   } catch {
-    return 'surface:1'
+    return false
   }
 }
 
-/** Get the current workspace ref. */
-export function currentWorkspace(): string {
+/** Get cmux version. */
+export function cmuxVersion(): string | null {
   try {
-    const info = JSON.parse(cmux('identify'))
-    return info.caller?.workspace_ref || 'workspace:1'
+    return cmux('version')
   } catch {
-    return 'workspace:1'
+    return null
   }
 }
 
-/** List all surfaces in the current workspace. */
-export function listSurfaces(): CmuxSurface[] {
-  const output = cmux('list-panels')
+// ---------------------------------------------------------------------------
+// Identity
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the caller's surface ref and workspace ref.
+ * Uses `cmux identify` which reliably returns the calling process's context,
+ * regardless of what the user has focused.
+ */
+export function identify(): { surface: string; workspace: string } {
+  const info = JSON.parse(cmux('identify'))
+  // Prefer caller (the process's own surface), fall back to focused surface
+  const surface = info.caller?.surface_ref || info.focused?.surface_ref
+  const workspace = info.caller?.workspace_ref || info.focused?.workspace_ref
+  if (!surface) throw new Error('cmux identify did not return a surface_ref')
+  return { surface, workspace: workspace || 'workspace:1' }
+}
+
+/** Get the caller's surface ref. */
+export function currentSurface(): string {
+  return identify().surface
+}
+
+/** Get the caller's workspace ref. */
+export function currentWorkspace(): string {
+  return identify().workspace
+}
+
+// ---------------------------------------------------------------------------
+// Surfaces
+// ---------------------------------------------------------------------------
+
+/** List all surfaces in a workspace. Defaults to the caller's workspace. */
+export function listSurfaces(workspace?: string): CmuxSurface[] {
+  const ws = workspace || currentWorkspace()
+  const output = cmux('list-panels', '--workspace', ws)
   if (!output) return []
 
   return output.split('\n')
     .filter(Boolean)
     .map((line, i) => {
-      const match = line.match(/^[*\s]*(surface:\d+)/)
-      return match ? { id: match[1], index: i } : null
+      // Format: "* surface:15  terminal  [focused]  "Title""
+      // or:     "  surface:20  terminal  "Title""
+      const match = line.match(/^([*\s]*)(surface:\d+)\s+\S+\s*(.*)$/)
+      if (!match) return null
+      const focused = match[3].includes('[focused]')
+      const titleMatch = match[3].match(/"([^"]*)"/)
+      return {
+        id: match[2],
+        index: i,
+        title: titleMatch?.[1] || '',
+        focused,
+      }
     })
     .filter((s): s is CmuxSurface => s !== null)
 }
 
-/** List all surface IDs in the current workspace. */
-export function listAllSurfaceIds(): string[] {
-  return listSurfaces().map((s) => s.id)
+/** List all surface IDs in a workspace. Defaults to the caller's workspace. */
+export function listAllSurfaceIds(workspace?: string): string[] {
+  return listSurfaces(workspace).map((s) => s.id)
 }
 
-/** Split a surface and return the new surface's ref. */
+/**
+ * Split relative to a specific surface and return the new surface ref.
+ * Always pass --surface so splits happen in the right place regardless of focus.
+ */
 export function splitSurface(
   direction: 'right' | 'down' | 'left' | 'up' = 'right',
+  relativeTo?: string,
 ): string {
-  // Snapshot surface IDs before split
-  const before = new Set(listAllSurfaceIds())
-  cmux('new-split', direction)
-  // Find the new surface by diffing
-  const after = listAllSurfaceIds()
-  const newId = after.find((id) => !before.has(id))
-  if (!newId) throw new Error('Split did not create a new surface')
-  return newId
+  const args = ['new-split', direction]
+  if (relativeTo) args.push('--surface', relativeTo)
+  // Output format: "OK surface:20 workspace:1"
+  const output = cmux(...args)
+  const match = output.match(/surface:\d+/)
+  if (!match) throw new Error(`Unexpected new-split output: ${output}`)
+  return match[0]
 }
 
-/** Close a surface. */
+/** Close a surface by ref. */
 export function closeSurface(surfaceId: string): void {
   try {
     cmux('close-surface', '--surface', surfaceId)
@@ -122,6 +143,21 @@ export function closeSurface(surfaceId: string): void {
   }
 }
 
+/** Rename a surface's tab for identification. */
+export function renameSurface(surfaceId: string, title: string): void {
+  cmux('rename-tab', title, '--surface', surfaceId)
+}
+
+/** Get the current title of a surface. */
+export function getSurfaceTitle(surfaceId: string): string {
+  const surfaces = listSurfaces()
+  return surfaces.find((s) => s.id === surfaceId)?.title || ''
+}
+
+// ---------------------------------------------------------------------------
+// I/O
+// ---------------------------------------------------------------------------
+
 /** Send text to a surface (pastes the text). */
 export function sendText(surfaceId: string, text: string): void {
   cmux('send', '--surface', surfaceId, text)
@@ -138,29 +174,6 @@ export function sendCommand(surfaceId: string, text: string): void {
   sendKey(surfaceId, 'Return')
 }
 
-/** Focus a surface. */
-export function focusSurface(surfaceId: string): void {
-  // Extract pane ref from surface — need to focus the pane
-  const panels = cmux('list-panels')
-  const lines = panels.split('\n').filter(Boolean)
-
-  // Just focus via the pane that contains this surface
-  // For now, use focus-pane on the pane associated with the surface
-  const panes = cmux('list-panes')
-  const paneLines = panes.split('\n').filter(Boolean)
-  // Try each pane to find the one containing our surface
-  for (const line of paneLines) {
-    const paneMatch = line.match(/^[*\s]*(pane:\d+)/)
-    if (paneMatch) {
-      const paneSurfaces = cmux('list-pane-surfaces', '--pane', paneMatch[1])
-      if (paneSurfaces.includes(surfaceId)) {
-        cmux('focus-pane', '--pane', paneMatch[1])
-        return
-      }
-    }
-  }
-}
-
 /** Read the screen content of a surface. */
 export function readScreen(surfaceId: string, lines?: number): string {
   const args = ['read-screen', '--surface', surfaceId]
@@ -168,38 +181,221 @@ export function readScreen(surfaceId: string, lines?: number): string {
   return cmux(...args)
 }
 
-/** Resize a pane in the given direction. */
-export function resizePane(paneRef: string, direction: 'L' | 'R' | 'U' | 'D', amount = 10): void {
-  cmux('resize-pane', '--pane', paneRef, `-${direction}`, '--amount', String(amount))
+// ---------------------------------------------------------------------------
+// Notifications & Sidebar
+// ---------------------------------------------------------------------------
+
+/** Send a desktop notification. */
+export function notify(title: string, body?: string, workspace?: string): void {
+  const args = ['notify', '--title', title]
+  if (body) args.push('--body', body)
+  if (workspace) args.push('--workspace', workspace)
+  try { cmux(...args) } catch {}
 }
 
-/** Get cmux version. */
-export function cmuxVersion(): string | null {
-  try {
-    return cmux('version')
-  } catch {
-    return null
+/** Set a status key in the sidebar. */
+export function setStatus(key: string, value: string, opts?: { icon?: string; color?: string; workspace?: string }): void {
+  const args = ['set-status', key, value]
+  if (opts?.icon) args.push('--icon', opts.icon)
+  if (opts?.color) args.push('--color', opts.color)
+  if (opts?.workspace) args.push('--workspace', opts.workspace)
+  try { cmux(...args) } catch {}
+}
+
+/** Clear a status key from the sidebar. */
+export function clearStatus(key: string, workspace?: string): void {
+  const args = ['clear-status', key]
+  if (workspace) args.push('--workspace', workspace)
+  try { cmux(...args) } catch {}
+}
+
+/** Set a progress bar in the sidebar (0.0 – 1.0). */
+export function setProgress(value: number, label?: string, workspace?: string): void {
+  const args = ['set-progress', String(Math.min(1, Math.max(0, value)))]
+  if (label) args.push('--label', label)
+  if (workspace) args.push('--workspace', workspace)
+  try { cmux(...args) } catch {}
+}
+
+/** Clear the sidebar progress bar. */
+export function clearProgress(workspace?: string): void {
+  const args = ['clear-progress']
+  if (workspace) args.push('--workspace', workspace)
+  try { cmux(...args) } catch {}
+}
+
+/** Append a log entry to the sidebar. */
+export function sidebarLog(message: string, level: 'info' | 'progress' | 'success' | 'warning' | 'error' = 'info', workspace?: string): void {
+  const args = ['log', '--level', level, '--source', 'cru']
+  if (workspace) args.push('--workspace', workspace)
+  args.push('--', message)
+  try { cmux(...args) } catch {}
+}
+
+/** Clear all sidebar log entries. */
+export function clearLog(workspace?: string): void {
+  const args = ['clear-log']
+  if (workspace) args.push('--workspace', workspace)
+  try { cmux(...args) } catch {}
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle status pills
+// ---------------------------------------------------------------------------
+
+/** Set the team lifecycle phase in the sidebar. Uses SF Symbol icons. */
+export function setPhase(phase: 'spawning' | 'working' | 'done', teamName: string, detail?: string, workspace?: string): void {
+  const phases = {
+    spawning: { icon: 'circle.dotted', color: '#a78bfa', label: 'spawning' },
+    working:  { icon: 'bolt.fill',     color: '#eab308', label: 'working' },
+    done:     { icon: 'checkmark.circle.fill', color: '#22c55e', label: 'done' },
   }
+  const p = phases[phase]
+  const value = detail ? `${p.label} — ${detail}` : p.label
+  setStatus('phase', value, { icon: p.icon, color: p.color, workspace })
 }
 
-/** Check if cmux socket is responding. */
-export function isCmuxAvailable(): boolean {
-  try {
-    cmux('ping')
-    return true
-  } catch {
-    return false
+/** Clear the phase pill. */
+export function clearPhase(workspace?: string): void {
+  clearStatus('phase', workspace)
+}
+
+// ---------------------------------------------------------------------------
+// Progress watcher
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn a background process that polls Claude Code's task system
+ * and updates the cmux sidebar with worker progress.
+ *
+ * Reads ~/.claude/tasks/<team>/*.json to track completed vs total tasks.
+ * Exits when all tasks are done or the team is closed.
+ */
+export function spawnProgressWatcher(teamName: string): void {
+  // Capture the current workspace now so the detached script doesn't rely on env vars
+  const ws = currentWorkspace()
+
+  const script = `
+    const { readFileSync, readdirSync, existsSync } = require('node:fs');
+    const { join } = require('node:path');
+    const { execFileSync } = require('node:child_process');
+    const { homedir } = require('node:os');
+
+    const ws = process.env.CRU_WORKSPACE;
+    const team = process.env.CRU_TEAM;
+    const cmux = (...args) => {
+      try { return execFileSync('cmux', [...args, '--workspace', ws], { encoding: 'utf-8', timeout: 5000 }).trim(); }
+      catch { return ''; }
+    };
+
+    const setPhase = (icon, color, label) => {
+      cmux('set-status', 'phase', label, '--icon', icon, '--color', color);
+    };
+
+    const tasksDir = join(homedir(), '.claude', 'tasks', team);
+    const panesFile = join(homedir(), '.claude', 'teams', team, 'cru-panes.json');
+    let lastCompleted = 0;
+    let staleCount = 0;
+
+    setPhase('bolt.fill', '#eab308', 'working');
+    let tasksStarted = false;
+
+    while (true) {
+      // Stop if team was closed (panes file removed)
+      if (!existsSync(panesFile)) break;
+
+      // Read task files
+      let tasks = [];
+      try {
+        if (existsSync(tasksDir)) {
+          for (const f of readdirSync(tasksDir)) {
+            if (!f.endsWith('.json')) continue;
+            try { tasks.push(JSON.parse(readFileSync(join(tasksDir, f), 'utf-8'))); } catch {}
+          }
+        }
+      } catch {}
+
+      if (tasks.length > 0) {
+        // First time tasks appear — clear the "N workers ready" progress bar
+        if (!tasksStarted) {
+          tasksStarted = true;
+          staleCount = 0;
+          cmux('clear-progress');
+        }
+
+        const completed = tasks.filter(t => t.status === 'completed').length;
+        const totalTasks = tasks.length;
+
+        if (completed !== lastCompleted) {
+          lastCompleted = completed;
+          staleCount = 0;
+
+          const ratio = totalTasks > 0 ? completed / totalTasks : 0;
+          cmux('set-progress', String(ratio), '--label', completed + '/' + totalTasks + ' tasks done');
+
+          if (completed > 0 && completed < totalTasks) {
+            cmux('log', '--level', 'progress', '--source', 'cru', '--', completed + '/' + totalTasks + ' tasks completed');
+            setPhase('bolt.fill', '#eab308', 'working — ' + completed + '/' + totalTasks + ' done');
+          }
+
+          if (completed >= totalTasks) {
+            cmux('set-progress', '1', '--label', 'All tasks done');
+            cmux('log', '--level', 'success', '--source', 'cru', '--', 'All ' + totalTasks + ' tasks completed');
+            cmux('notify', '--title', '◫ ' + team, '--body', 'All tasks completed');
+            setPhase('checkmark.circle.fill', '#22c55e', 'done');
+            cmux('set-status', 'team', team + ' ✓', '--icon', 'person.2.fill', '--color', '#22c55e');
+            break;
+          }
+        } else {
+          // Only count staleness once tasks have appeared
+          staleCount++;
+        }
+      }
+
+      // Give up after 10 min of no progress (only counted after tasks appear)
+      if (tasksStarted && staleCount > 300) break;
+
+      Bun.sleepSync(2000);
+    }
+  `;
+
+  // Spawn detached so cru can exit — pass values via env to avoid injection
+  Bun.spawn(['bun', '-e', script], {
+    detached: true,
+    stdio: ['ignore', 'ignore', 'ignore'],
+    env: { ...process.env, CRU_WORKSPACE: ws, CRU_TEAM: teamName },
+  }).unref()
+}
+
+// ---------------------------------------------------------------------------
+// Focus
+// ---------------------------------------------------------------------------
+
+/** Focus a surface. */
+export function focusSurface(surfaceId: string): void {
+  const panes = cmux('list-panes')
+  for (const line of panes.split('\n').filter(Boolean)) {
+    const paneMatch = line.match(/^[*\s]*(pane:\d+)/)
+    if (!paneMatch) continue
+    const paneSurfaces = cmux('list-pane-surfaces', '--pane', paneMatch[1])
+    if (paneSurfaces.includes(surfaceId)) {
+      cmux('focus-pane', '--pane', paneMatch[1])
+      return
+    }
   }
 }
 
+// ---------------------------------------------------------------------------
+// Grid builder
+// ---------------------------------------------------------------------------
+
 /**
- * Build a grid layout for cmux using iterative splits.
+ * Build a grid layout using iterative splits.
  *
- * cmux doesn't have tmux-style layout strings, so we build the grid
- * imperatively: split the workspace into lead + grid area, then split
- * the grid area into rows and columns.
+ * All splits use explicit --surface targeting so they work regardless
+ * of what the user has focused. No focus changes needed.
  *
- * Returns the surface IDs of the created worker panes.
+ * Returns the surface refs of the created worker panes.
  */
 export function buildGrid(
   leadSurface: string,
@@ -210,64 +406,41 @@ export function buildGrid(
   const isHorizontal = conf.lead.position === 'left' || conf.lead.position === 'right'
   const workerSurfaces: string[] = []
 
-  // Create the first worker by splitting from the lead
   const firstSplitDir = isHorizontal
     ? (conf.lead.position === 'left' ? 'right' : 'left')
     : (conf.lead.position === 'top' ? 'down' : 'up')
 
-  // Focus lead before splitting
-  focusSurface(leadSurface)
-  Bun.sleepSync(100)
-
-  const firstWorker = splitSurface(firstSplitDir as 'right' | 'down' | 'left' | 'up')
+  // First worker: split relative to the lead surface
+  const firstWorker = splitSurface(firstSplitDir as 'right' | 'down' | 'left' | 'up', leadSurface)
   workerSurfaces.push(firstWorker)
   Bun.sleepSync(100)
 
-  // Create remaining workers by splitting existing ones
-  // Strategy: fill row by row
-  // Row 0 already has 1 pane. For row 0, add more columns.
-  // Then for each additional row, split an existing row pane downward.
+  if (workerCount <= 1) return workerSurfaces
 
-  // First, complete row 0 by splitting horizontally
   const colDir = isHorizontal ? 'down' : 'right'
   const rowDir = isHorizontal ? 'right' : 'down'
-
   let created = 1
-  if (workerCount <= 1) return workerSurfaces
 
-  // Build column by column in the first row
+  // Build columns in row 0 — each splits relative to the previous worker
   for (let c = 1; c < cols && created < workerCount; c++) {
-    focusSurface(workerSurfaces[workerSurfaces.length - 1])
-    Bun.sleepSync(100)
-    const s = splitSurface(rowDir as 'right' | 'down')
+    const s = splitSurface(rowDir as 'right' | 'down', workerSurfaces[workerSurfaces.length - 1])
     workerSurfaces.push(s)
     created++
     Bun.sleepSync(100)
   }
 
-  // Now add additional rows by splitting each column pane
+  // Add additional rows by splitting column panes downward
   for (let r = 1; r < rows && created < workerCount; r++) {
     for (let c = 0; c < cols && created < workerCount; c++) {
-      // Split the pane in row 0, column c (index = c)
-      const targetIdx = c
-      if (targetIdx < workerSurfaces.length) {
-        // Find the bottommost pane in this column
-        // For simplicity, split the pane at position c + (r-1)*cols
-        const splitTarget = workerSurfaces[targetIdx + (r - 1) * cols]
-        if (splitTarget) {
-          focusSurface(splitTarget)
-          Bun.sleepSync(100)
-          const s = splitSurface(colDir as 'right' | 'down')
-          workerSurfaces.push(s)
-          created++
-          Bun.sleepSync(100)
-        }
+      const splitTarget = workerSurfaces[c + (r - 1) * cols]
+      if (splitTarget) {
+        const s = splitSurface(colDir as 'right' | 'down', splitTarget)
+        workerSurfaces.push(s)
+        created++
+        Bun.sleepSync(100)
       }
     }
   }
 
-  // Focus lead pane at the end
-  focusSurface(leadSurface)
-
   return workerSurfaces
 }

package/src/lib/mirror.ts

@@ -18,7 +18,7 @@
 import { execFileSync } from 'node:child_process'
 import { readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import { splitTerminal, sendCommand } from './ghostty'
+import { splitTerminal, sendCommand as ghosttySendCommand } from './ghostty'
 
 /** Run a tmux command on a specific socket (or default). */
 function tmuxSocket(args: string[], socket?: string): string {
@@ -141,9 +141,51 @@ export function mirrorSingleWorker(
   Bun.sleepSync(300)
 
   // Attach to the view session via the custom socket
-  sendCommand(newTermId, `tmux -L ${socket} attach -t ${viewName}`)
+  ghosttySendCommand(newTermId, `tmux -L ${socket} attach -t ${viewName}`)
   Bun.sleepSync(200)
 
   console.log(`  [mirror] ${windowName} (${paneId}) → ghostty:${newTermId}`)
   return { ghosttyTerminal: newTermId, viewSession: viewName }
 }
+
+/**
+ * Mirror a single tmux worker pane into a cmux split.
+ * Same approach as Ghostty mirroring but uses cmux CLI for splits.
+ */
+export function mirrorWorkerToCmux(
+  socket: string,
+  session: string,
+  paneId: string,
+  index: number,
+  splitTarget: string,
+  splitDirection: 'right' | 'down',
+): { cmuxSurface: string; viewSession: string } {
+  const { splitSurface, sendCommand: cmuxSendCommand } = require('./cmux')
+
+  const windowName = `worker-${index + 1}`
+  const viewName = `view-${index + 1}`
+
+  // Break pane into its own tmux window
+  try {
+    tmuxSocket(['break-pane', '-s', paneId, '-d', '-n', windowName], socket)
+  } catch (e: any) {
+    console.error(`  [mirror] break-pane ${paneId}: ${e.message}`)
+  }
+
+  // Create a session group member pointing at the worker's window
+  try { tmuxSocket(['kill-session', '-t', viewName], socket) } catch {}
+  tmuxSocket(['new-session', '-d', '-t', session, '-s', viewName], socket)
+  tmuxSocket(['set-option', '-t', viewName, 'status', 'off'], socket)
+  tmuxSocket(['select-window', '-t', `${viewName}:${windowName}`], socket)
+
+  // Create cmux split relative to the target surface
+  const newSurface = splitSurface(splitDirection, splitTarget)
+  Bun.sleepSync(300)
+
+  // Attach to the view session via the custom socket
+  cmuxSendCommand(newSurface, `tmux -L ${socket} attach -t ${viewName}`)
+  Bun.sleepSync(200)
+
+  console.log(`  [mirror] ${windowName} (${paneId}) → cmux:${newSurface}`)
+  return { cmuxSurface: newSurface, viewSession: viewName }
+}

package/src/lib/panes.ts

@@ -9,6 +9,7 @@ export interface PaneRecord {
   workers: Array<{ name: string; paneId: string; color: string }>
   createdAt: number
   backend?: 'tmux' | 'ghostty' | 'cmux'
+  leadOriginalTitle?: string
 }
 
 function panePath(teamName: string): string {