@humanu/orchestra 0.5.2 → 0.5.3

package/resources/api/tmux.sh

@@ -0,0 +1,1266 @@
+#!/bin/bash
+
+###############################################################################
+# tmux.sh – Dedicated tmux session management API
+# ---------------------------------------------------------------------------
+# This script provides a clean API for all tmux session operations.
+# It can be sourced by other modules that need tmux functionality.
+###############################################################################
+
+# Ensure we have access to core utilities
+if ! declare -f repo_root >/dev/null 2>&1 && ! declare -f git_repo_root >/dev/null 2>&1; then
+  echo "Error: tmux.sh must be sourced from gw.sh or have core utilities available" >&2
+  return 1 2>/dev/null || exit 1
+fi
+
+# Use git_repo_root if available, otherwise fallback to repo_root
+if declare -f git_repo_root >/dev/null 2>&1; then
+  repo_root() { git_repo_root; }
+fi
+
+# --------------------------- Tmux Core API ----------------------------------
+
+# Session delimiter (hardcoded)
+# Note: tmux session names cannot contain ':'; use a safe delimiter
+ORCHESTRA_SESSION_DELIM="__"
+
+# Helper: return delimiter
+_tmux_delim() { echo "$ORCHESTRA_SESSION_DELIM"; }
+
+# Helper: sanitize tmux session name for filesystem usage
+_orchestra_history_key() {
+  local key="$1"
+  key="${key//\//_}"
+  key=$(echo "$key" | tr '[:space:]' '_')
+  key=$(echo "$key" | tr -c '[:alnum:]_-' '_')
+  while [[ "$key" == *"__"* ]]; do
+    key="${key//__/_}"
+  done
+  key="${key##_}"
+  key="${key%%_}"
+  echo "$key"
+}
+
+# Helper: absolute path to the command hook script (if present)
+_orchestra_command_hook() {
+  local root
+  root="$(repo_root)"
+  if [[ -z "$root" ]]; then
+    echo ""
+    return
+  fi
+  local hook="$root/shell/orchestra-command-hook.sh"
+  if [[ -f "$hook" ]]; then
+    echo "$hook"
+  else
+    echo ""
+  fi
+}
+
+# Source the command hook inside a tmux session to enable command history logging
+_tmux_source_command_hook() {
+  local session="$1"
+  local hook
+  hook="$(_orchestra_command_hook)"
+  if [[ -z "$hook" ]]; then
+    return
+  fi
+  if ! tmux_session_exists "$session"; then
+    return
+  fi
+  local pane_cmd
+  pane_cmd=$(tmux display-message -t "${session}:0" -p '#{pane_current_command}' 2>/dev/null || echo "")
+  case "$pane_cmd" in
+    bash|zsh|sh|fish|dash|ksh)
+      ;;
+    *)
+      return
+      ;;
+  esac
+  # Send sourcing command to the primary pane. The hook is idempotent and will
+  # simply return if it's already been installed in that shell.
+  tmux send-keys -t "${session}:0" "source '$hook'" C-m 2>/dev/null || true
+}
+
+# Helper: orchestra prefix including delimiter
+_tmux_orch_prefix() { printf "orchestra%s" "$( _tmux_delim )"; }
+
+# Helper: split a string by multi-char delimiter into bash array named by ref
+# Usage: _tmux_split_by_delim "string" "::" out_array_name
+_tmux_split_by_delim() {
+  local _s="$1" _d="$2" _ref="$3"
+  local _arr=()
+  if [[ -z "$_d" ]]; then
+    _arr=("$_s")
+  else
+    while :; do
+      if [[ "$_s" == *"$_d"* ]]; then
+        _arr+=("${_s%%"$_d"*}")
+        _s="${_s#*"$_d"}"
+      else
+        _arr+=("$_s")
+        break
+      fi
+    done
+  fi
+  # Use printf with %q to properly quote array elements for eval
+  local _quoted=()
+  local _item
+  for _item in "${_arr[@]}"; do
+    printf -v _q "%q" "$_item"
+    _quoted+=("$_q")
+  done
+  eval "$_ref=( ${_quoted[*]} )"
+}
+
+
+# Check if tmux is available
+tmux_available() {
+  have_cmd tmux
+}
+
+# Check if currently inside a tmux session
+tmux_inside_session() {
+  [[ -n "${TMUX-}" ]]
+}
+
+# Generate random readable name for tmux sessions
+tmux_generate_readable_name() {
+  local adjectives=(
+    "swift" "brave" "clever" "gentle" "bright" "calm" "eager" "fierce" "happy" "kind"
+    "lively" "noble" "proud" "quick" "smart" "wise" "bold" "cool" "daring" "epic"
+    "fuzzy" "jolly" "lucky" "merry" "peppy" "rosy" "sunny" "zesty" "crisp" "fresh"
+  )
+  local animals=(
+    "bear" "wolf" "fox" "eagle" "hawk" "lion" "tiger" "panda" "otter" "seal"
+    "whale" "shark" "dolphin" "falcon" "raven" "deer" "moose" "lynx" "badger" "heron"
+    "phoenix" "dragon" "griffin" "unicorn" "pegasus" "kraken" "sphinx" "chimera" "hydra" "basilisk"
+  )
+  
+  local adj_idx=$((RANDOM % ${#adjectives[@]}))
+  local animal_idx=$((RANDOM % ${#animals[@]}))
+  
+  echo "${adjectives[$adj_idx]}_${animals[$animal_idx]}"
+}
+
+# --------------------------- Session Management -----------------------------
+
+# Create a new tmux session
+# Usage: tmux_create_session <session_name> <working_directory>
+tmux_create_session() {
+  local session_name="$1"
+  local working_dir="$2"
+  
+  if ! tmux_available; then
+    err "tmux not installed"
+    return 1
+  fi
+  
+  # Get repository info from the working directory context
+  local repo_name=""
+  local branch_name=""
+  local old_pwd="$PWD"
+  
+  # Change to working directory to get accurate git info
+  cd "$working_dir" 2>/dev/null || true
+  
+  if command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; then
+    repo_name="$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")"
+    branch_name="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "detached")"
+  fi
+  
+  # Restore original directory
+  cd "$old_pwd" 2>/dev/null || true
+  
+  # Ensure orchestra prefix (configurable delimiter) on session name to mark origin
+  local ORCH_PREFIX
+  ORCH_PREFIX="$(_tmux_orch_prefix)"
+  if [[ "$session_name" != ${ORCH_PREFIX}* ]]; then
+    session_name="${ORCH_PREFIX}${session_name}"
+  fi
+  
+  # Create session with custom Orchestra status configuration
+  tmux new-session -Ad -s "$session_name" -c "$working_dir" >/dev/null 2>&1 || {
+    err "Failed to create tmux session: $session_name"
+    return 1
+  }
+  
+  # Customize the default status bar to include Orchestra info on the left
+  if [[ -n "$repo_name" ]]; then
+    # Set custom status-left with Orchestra branding without full path
+    # Example: Go back (detach): Ctrl+b,d | Copy (scroll) mode: Ctrl+b,[ | Worktree: main
+    local worktree_name=""
+    if [[ -n "$branch_name" && "$branch_name" != "detached" ]]; then
+      worktree_name="$branch_name"
+    else
+      worktree_name="$(basename "$working_dir")"
+    fi
+    tmux set-option -t "$session_name" status-left "Go back (detach): Ctrl+b,d | Copy (scroll) mode: Ctrl+b,[ | Worktree: ${worktree_name}" >/dev/null 2>&1 || true
+    
+    # Increase status-left length to accommodate the message
+    tmux set-option -t "$session_name" status-left-length 120 >/dev/null 2>&1 || true
+  fi
+  
+  echo "$session_name"
+}
+
+# Generate a short hash from a path for unique session identification
+# Usage: tmux_path_hash <path>
+tmux_path_hash() {
+  local path="$1"
+  # Use MD5 hash of the path, take first 8 chars
+  # Works on both macOS and Linux
+  if command -v md5sum >/dev/null 2>&1; then
+    echo -n "$path" | md5sum | cut -c1-8
+  elif command -v md5 >/dev/null 2>&1; then
+    echo -n "$path" | md5 -q | cut -c1-8
+  else
+    # Fallback: use cksum if neither md5 available
+    echo -n "$path" | cksum | cut -d' ' -f1 | cut -c1-8
+  fi
+}
+
+# Alias for backward compatibility
+tmux_repo_hash() {
+  tmux_path_hash "$1"
+}
+
+# Ensure a session exists for slug+name in worktree; prints session name
+# Creates sessions with format: [worktreename]_[worktreetreehash]_[datetime]_[readable_name]
+# Usage: tmux_ensure_session <slug> <name> <worktree_path>
+tmux_ensure_session() {
+  local slug="$1"
+  local name="$2" 
+  local wt="$3"
+  local d
+  d="$(_tmux_delim)"
+  local date_part time_part
+  date_part="$(date +%Y%m%d)"
+  time_part="$(date +%H%M%S)"
+  
+  # Use a repo-scoped hash to avoid cross-repo collisions
+  # Hash the absolute worktree path (backward-compat listing supports old slug-hash)
+  local worktree_hash
+  worktree_hash="$(tmux_path_hash "$wt")"
+  
+  # If name is provided, use it; otherwise generate a random readable name with auto_ prefix
+  if [[ -z "$name" || "$name" == "main" ]]; then
+    name="auto_$(tmux_generate_readable_name)"
+  fi
+  
+  local sess="${slug}${d}${worktree_hash}${d}${date_part}${d}${time_part}${d}${name}"
+  tmux_create_session "$sess" "$wt"
+  _tmux_source_command_hook "$sess"
+}
+
+# Check if a session exists
+# Usage: tmux_session_exists <session_name>
+tmux_session_exists() {
+  local session_name="$1"
+  tmux_available && tmux has-session -t "$session_name" 2>/dev/null
+}
+
+# Kill/delete a tmux session
+# Usage: tmux_kill_session <session_name>
+tmux_kill_session() {
+  local session_name="$1"
+  
+  if ! tmux_available; then
+    err "tmux not installed"
+    return 1
+  fi
+  
+  tmux kill-session -t "$session_name" 2>/dev/null || {
+    err "Failed to kill session: $session_name"
+    return 1
+  }
+}
+
+# Attach or switch to session
+# Usage: tmux_attach_session <session_name>
+tmux_attach_session() {
+  local sess="$1"
+  
+  if ! tmux_available; then
+    err "tmux not installed"
+    return 1
+  fi
+
+  _tmux_source_command_hook "$sess"
+  
+  # Get repository info for terminal title and banner update
+  local repo_name=""
+  local branch_name=""
+  local session_dir=""
+  
+  # Try to get the session's working directory
+  session_dir="$(tmux display-message -t "$sess" -p '#{pane_current_path}' 2>/dev/null || echo "")"
+  
+  if [[ -n "$session_dir" ]] && [[ -d "$session_dir" ]]; then
+    # Get git info from session's directory
+    local old_pwd="$PWD"
+    cd "$session_dir" 2>/dev/null || true
+    
+    if command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; then
+      repo_name="$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")"
+      branch_name="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "detached")"
+    fi
+    
+    cd "$old_pwd" 2>/dev/null || true
+  else
+    # Fallback to current directory
+    if command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; then
+      repo_name="$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")"
+      branch_name="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "detached")"
+    fi
+  fi
+  
+  # Set terminal window title (works in most terminal emulators)
+  if [[ -n "$repo_name" ]]; then
+    printf "\033]0;🎼 Orchestra: %s [%s]\007" "$repo_name" "$branch_name" >/dev/tty 2>/dev/null || true
+  fi
+  
+  # Show welcome message when attaching
+  if [[ -n "$repo_name" ]]; then
+    tmux display-message -t "$sess" -d 2000 \
+      "🎼 Orchestra Session | Repository: $repo_name | Branch: $branch_name" 2>/dev/null || true
+  fi
+
+  # Ensure status-left shows Orchestra help without full path
+  local worktree_name=""
+  if [[ -n "$branch_name" && "$branch_name" != "detached" ]]; then
+    worktree_name="$branch_name"
+  else
+    # Fallback to directory name of session path if available
+    if [[ -n "$session_dir" && -d "$session_dir" ]]; then
+      worktree_name="$(basename "$session_dir")"
+    else
+      worktree_name="$branch_name"
+    fi
+  fi
+  tmux set-option -t "$sess" status-left "Go back (detach): Ctrl+b,d | Copy (scroll) mode: Ctrl+b,[ | Worktree: ${worktree_name}" >/dev/null 2>&1 || true
+  tmux set-option -t "$sess" status-left-length 120 >/dev/null 2>&1 || true
+  
+  if tmux_inside_session; then
+    tmux switch-client -t "$sess" >/dev/null 2>&1 || true
+  else
+    tmux attach -t "$sess" >/dev/null 2>&1 || true
+  fi
+}
+
+# Rename a tmux session while preserving the worktree prefix, repo hash, and datetime
+# Usage: tmux_rename_session <old_session_name> <new_name>
+tmux_rename_session() {
+  local old_session="$1"
+  local new_name="$2"
+  
+  if ! tmux_available; then
+    err "tmux not installed"
+    return 1
+  fi
+  
+  local d ORCH_PREFIX
+  d="$(_tmux_delim)"
+  ORCH_PREFIX="$(_tmux_orch_prefix)"
+  
+  # Detect and strip orchestra prefix for parsing
+  local orch=""
+  local base="$old_session"
+  if [[ "$base" == ${ORCH_PREFIX}* ]]; then
+    orch="$ORCH_PREFIX"
+    base="${base#${ORCH_PREFIX}}"
+  fi
+  
+  # Split by current delimiter and scan from the right to tolerate delimiter inside segments
+  local parts
+  _tmux_split_by_delim "$base" "$d" parts
+  
+  local n=${#parts[@]}
+  local idx_time=-1 idx_date=-1 idx_hash=-1
+  local i
+  for (( i=n-1; i>=0; i-- )); do
+    if [[ ${parts[$i]} =~ ^[0-9]{6}$ ]]; then idx_time=$i; break; fi
+  done
+  if (( idx_time > 0 )) && [[ ${parts[$((idx_time-1))]} =~ ^[0-9]{8}$ ]]; then
+    idx_date=$((idx_time-1))
+  fi
+  if (( idx_date > 0 )) && [[ ${parts[$((idx_date-1))]} =~ ^[0-9a-f]{8}$ ]]; then
+    idx_hash=$((idx_date-1))
+  fi
+
+  local prefix=""
+  if (( idx_time >= 0 && idx_date >= 0 )); then
+    # Build prefix: slug + d + [hash + d] + date + d + time + d
+    local upto=$idx_time
+    local j
+    for (( j=0; j<=upto; j++ )); do
+      if (( j > 0 )); then prefix+="$d"; fi
+      prefix+="${parts[$j]}"
+    done
+    prefix+="$d"
+
+    # Debug logging for rename parsing
+    if [[ -n "${GW_DEBUG_RENAME-}" || -n "${DEBUG-}" ]]; then
+      >&2 echo "[orchestra] rename DEBUG: old='$old_session' base='$base' delim='$d'"
+      >&2 echo "[orchestra] parts: ${parts[*]}"
+      >&2 echo "[orchestra] idx_time=$idx_time idx_date=$idx_date idx_hash=$idx_hash"
+      >&2 echo "[orchestra] prefix='${orch}${prefix}' new_name='$new_name'"
+    fi
+  else
+    err "Invalid session format"
+    return 1
+  fi
+  
+  local new_session="${orch}${prefix}${new_name}"
+  
+  tmux rename-session -t "$old_session" "$new_session" 2>/dev/null || {
+    err "Failed to rename session"
+    return 1
+  }
+  >&2 echo "✏️  Renamed session to: $new_name"
+  return 0
+}
+
+# --------------------------- Session Discovery ------------------------------
+
+# Get tmux sessions for a slug prefix; prints session names sorted by last attached/activity
+# Expected session format: [worktreename]_[worktreehash]_[datetime]_[readable_name]
+# Usage: tmux_list_sessions_for_slug <slug> [worktree_path]
+tmux_list_sessions_for_slug() {
+  local slug="$1"
+  local worktree_path="${2:-}"
+  tmux_available || return 0
+  
+  local d ORCH_PREFIX
+  d="$(_tmux_delim)"
+  ORCH_PREFIX="$(_tmux_orch_prefix)"
+  
+  # If worktree_path provided, match both old (absolute-path hash) and new (slug hash)
+  if [[ -n "$worktree_path" ]]; then
+    local hash_slug hash_path
+    hash_slug="$(tmux_path_hash "$slug")"
+    hash_path="$(tmux_path_hash "$worktree_path")"
+    local p1_new="${ORCH_PREFIX}${slug}${d}${hash_slug}${d}"
+    local p2_new="${slug}${d}${hash_slug}${d}"
+    local p1_old="${ORCH_PREFIX}${slug}${d}${hash_path}${d}"
+    local p2_old="${slug}${d}${hash_path}${d}"
+    
+    # List sessions with either hash variant
+    tmux list-sessions -F '#{session_name}|||#{session_last_attached}|||#{session_activity}' 2>/dev/null \
+      | sed 's/|||/\t/g' \
+      | awk -v a="$p1_new" -v b="$p2_new" -v c="$p1_old" -v d="$p2_old" 'BEGIN{FS="\t"} index($1, a)==1 || index($1, b)==1 || index($1, c)==1 || index($1, d)==1 {print $1"\t"$2"\t"$3}' \
+      | sort -t $'\t' -k2,2nr -k3,3nr \
+      | awk -F '\t' '{print $1}' | awk '!seen[$0]++' || true
+  else
+    # New-format prefix matching without hash: orchestra__slug__... or slug__...
+    local prefix1="${ORCH_PREFIX}${slug}${d}"
+    local prefix2="${slug}${d}"
+    tmux list-sessions -F '#{session_name}|||#{session_last_attached}|||#{session_activity}' 2>/dev/null \
+      | sed 's/|||/\t/g' \
+      | awk -v p1="$prefix1" -v p2="$prefix2" 'BEGIN{FS="\t"} index($1, p1)==1 || index($1, p2)==1 {print $1"\t"$2"\t"$3}' \
+      | sort -t $'\t' -k2,2nr -k3,3nr \
+      | awk -F '\t' '{print $1}' || true
+  fi
+}
+
+# List all tmux sessions
+# Usage: tmux_list_all_sessions
+tmux_list_all_sessions() {
+  tmux_available || return 0
+  tmux list-sessions -F '#{session_name}' 2>/dev/null || true
+}
+
+# Find sessions matching a pattern
+# Usage: tmux_find_session <pattern>
+tmux_find_session() {
+  local pattern="$1"
+  
+  if ! tmux_available; then
+    return 1
+  fi
+  
+  # Try exact match first
+  if tmux_session_exists "$pattern"; then
+    echo "$pattern"
+    return 0
+  fi
+  
+  # Try pattern match
+  tmux_list_all_sessions | grep -E "$pattern" | head -1 || true
+}
+
+# --------------------------- Session Information ----------------------------
+
+# Helper function to format session display names
+# Input: session_content (e.g., "opencode_fixing_auth_bug" or "my_feature_work")
+# Output: "Opencode: Fixing Auth Bug" or "My Feature Work"
+format_session_display_name() {
+  local session_content="$1"
+  
+  # Known app prefixes and their display names
+  local known_apps=("opencode" "running" "ssh" "docker" "k8s" "git" "db")
+  local app_prefix=""
+  local description=""
+  
+  # Check if session starts with a known app prefix
+  for app in "${known_apps[@]}"; do
+    if [[ "$session_content" =~ ^${app}_ ]]; then
+      app_prefix="$app"
+      # Remove the app prefix and following underscore
+      description="${session_content#${app}_}"
+      break
+    fi
+  done
+  
+  # If no app prefix found, treat whole string as description
+  if [[ -z "$app_prefix" ]]; then
+    description="$session_content"
+  fi
+  
+  # Convert underscores and hyphens to spaces and apply sentence case
+  description="$(echo "$description" | tr '_-' ' ')"
+  
+  # Apply sentence case (capitalize first letter of each word)
+  description="$(echo "$description" | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2));}1')"
+  
+  # Format final display name
+  if [[ -n "$app_prefix" ]]; then
+    # Capitalize app name and format as "App: Description"
+    local app_display="$(echo "$app_prefix" | awk '{print toupper(substr($1,1,1)) tolower(substr($1,2))}')"
+    echo "${app_display}: ${description}"
+  else
+    echo "$description"
+  fi
+}
+
+# Parse session name and format for display
+# Input: session_name (format: worktreename_repohash_YYYYMMDD_HHMMSS_readable_name or old formats)
+# Output: "App: Description" or formatted display name
+# Usage: tmux_format_session_display <session_name>
+tmux_format_session_display() {
+  local session_name="$1"
+  
+  # Handle temporary renaming sessions first
+  if [[ "$session_name" =~ _renaming$ ]]; then
+    # Extract base name before _renaming suffix
+    local base_name="${session_name%_renaming}"
+    # Recursively process the base name to get proper display
+    tmux_format_session_display "$base_name"
+    return $?
+  fi
+  
+  # Strip leading orchestra_ prefix if present
+  if [[ "$session_name" =~ ^orchestra_(.+)$ ]]; then
+    session_name="${BASH_REMATCH[1]}"
+  fi
+  
+  # New format with repo hash: worktreename_repohash_YYYYMMDD_HHMMSS_readable_name
+  if [[ "$session_name" =~ ^[^_]+_[a-f0-9]{8}_([0-9]{8})_([0-9]{6})_(.+)$ ]]; then
+    local date_part="${BASH_REMATCH[1]}"  # YYYYMMDD
+    local time_part="${BASH_REMATCH[2]}"  # HHMMSS
+    local readable_name="${BASH_REMATCH[3]}"  # readable_name
+    
+    # Parse date: YYYYMMDD -> Jul 21
+    local year="${date_part:0:4}"
+    local month="${date_part:4:2}"
+    local day="${date_part:6:2}"
+    
+    # Parse time: HHMMSS -> 12:30am
+    local hour="${time_part:0:2}"
+    local minute="${time_part:2:2}"
+    
+    # Convert to 12-hour format
+    local ampm="am"
+    local display_hour="$hour"
+    if [[ "$hour" -ge 12 ]]; then
+      ampm="pm"
+      if [[ "$hour" -gt 12 ]]; then
+        display_hour=$((hour - 12))
+      fi
+    fi
+    if [[ "$hour" == "00" ]]; then
+      display_hour="12"
+    fi
+    
+    # Remove leading zero from hour
+    display_hour="${display_hour#0}"
+    
+    # Convert month number to name
+    local month_names=("" "Jan" "Feb" "Mar" "Apr" "May" "Jun" "Jul" "Aug" "Sep" "Oct" "Nov" "Dec")
+    local month_name="${month_names[${month#0}]}"
+    
+    # Remove leading zero from day
+    local display_day="${day#0}"
+    
+    # Format the readable name with proper formatting
+    local formatted_name="$(format_session_display_name "$readable_name")"
+    
+    echo "${formatted_name} (${month_name} ${display_day} ${display_hour}:${minute}${ampm})"
+  # Fallback: Try format without repo hash: appname_description_YYYYMMDD_HHMMSS
+  elif [[ "$session_name" =~ ^(.*)_[0-9]{8}_[0-9]{6}$ ]]; then
+    local session_content="${BASH_REMATCH[1]}"  # appname_description
+    
+    # Convert to proper display format with app prefix
+    local formatted_name="$(format_session_display_name "$session_content")"
+    echo "$formatted_name"
+  else
+    # Check for old format without repo hash: worktreename_YYYYMMDD_HHMMSS_readable_name
+    if [[ "$session_name" =~ ^[^_]+_([0-9]{8})_([0-9]{6})_(.+)$ ]]; then
+      local date_part="${BASH_REMATCH[1]}"  # YYYYMMDD
+      local time_part="${BASH_REMATCH[2]}"  # HHMMSS
+      local readable_name="${BASH_REMATCH[3]}"  # readable_name
+      
+      # Parse date: YYYYMMDD -> Jul 21
+      local year="${date_part:0:4}"
+      local month="${date_part:4:2}"
+      local day="${date_part:6:2}"
+      
+      # Parse time: HHMMSS -> 12:30am
+      local hour="${time_part:0:2}"
+      local minute="${time_part:2:2}"
+      
+      # Convert to 12-hour format
+      local ampm="am"
+      local display_hour="$hour"
+      if [[ "$hour" -ge 12 ]]; then
+        ampm="pm"
+        if [[ "$hour" -gt 12 ]]; then
+          display_hour=$((hour - 12))
+        fi
+      fi
+      if [[ "$hour" == "00" ]]; then
+        display_hour="12"
+      fi
+      
+      # Remove leading zero from hour
+      display_hour="${display_hour#0}"
+      
+      # Convert month number to name
+      local month_names=("" "Jan" "Feb" "Mar" "Apr" "May" "Jun" "Jul" "Aug" "Sep" "Oct" "Nov" "Dec")
+      local month_name="${month_names[${month#0}]}"
+      
+      # Remove leading zero from day
+      local display_day="${day#0}"
+      
+      # Format the readable name with proper formatting
+      local formatted_name="$(format_session_display_name "$readable_name")"
+      
+      echo "${formatted_name} (${month_name} ${display_day} ${display_hour}:${minute}${ampm})"
+    else
+      # Fallback for sessions that don't match either format
+      echo "$session_name"
+    fi
+  fi
+}
+
+# Get active pane id for a session (best effort)
+# Usage: tmux_get_active_pane <session_name>
+tmux_get_active_pane() {
+  local s="$1"
+  tmux_available || return 1
+  
+  # Find active window id
+  local win
+  win="$(tmux list-windows -t "$s" -F '#{window_active} #{window_id}' 2>/dev/null | awk '$1==1{print $2; exit}')" || true
+  [[ -z "$win" ]] && return 1
+  
+  # Find active pane id within that window
+  tmux list-panes -t "$win" -F '#{pane_active} #{pane_id}' 2>/dev/null | awk '$1==1{print $2; exit}' || true
+}
+
+# Capture enhanced session preview showing current terminal view (~15 lines)
+# Usage: tmux_session_preview <session_name>
+tmux_session_preview() {
+  local s="$1"
+  tmux_available || { echo "(tmux not installed)"; return 0; }
+  
+  local pane
+  pane="$(tmux_get_active_pane "$s" || true)"
+  if [[ -z "$pane" ]]; then
+    echo "(no active pane found)"
+    return 0
+  fi
+  
+  # Capture from the bottom of the pane with ANSI escape sequences preserved
+  # -e flag preserves escape sequences for colors and formatting
+  # -S - means start from the current position (bottom)
+  # -E - means end at the current position
+  # This captures the visible content from the bottom up
+  local txt
+  txt="$(tmux capture-pane -e -p -S - -E - -t "$pane" 2>/dev/null)"
+  
+  if [[ -z "$txt" ]]; then
+    echo "(no output yet)"
+    return 0
+  fi
+  
+  # Also get the terminal type for color mode detection
+  local term_info
+  term_info="$(tmux show-environment -t "$s" TERM 2>/dev/null | cut -d= -f2 || echo "unknown")"
+  
+  # Check if true color is supported in this session
+  local has_rgb="false"
+  if tmux show-options -t "$s" -s terminal-overrides 2>/dev/null | grep -q "RGB"; then
+    has_rgb="true"
+  fi
+  
+  # For ANSI-preserved preview with color mode info
+  # Add markers for the Rust parser to detect color capabilities
+  if [[ "$has_rgb" == "true" || "$term_info" == *"direct"* || "$term_info" == *"truecolor"* ]]; then
+    echo "<<<COLORMODE:RGB>>>"
+  elif [[ "$term_info" == *"256color"* ]]; then
+    echo "<<<COLORMODE:256>>>"
+  else
+    echo "<<<COLORMODE:16>>>"
+  fi
+  echo "$txt"
+  
+  # If no content after processing, show placeholder
+  if [[ -z "$txt" ]]; then
+    echo "(session active, no visible output)"
+    return 0
+  fi
+  
+  echo "$txt"
+}
+
+# --------------------------- Advanced Operations ----------------------------
+
+# Send keys to a session and press Enter
+# Usage: tmux_send_keys <session_name> <command...>
+tmux_send_keys() {
+  local session_name="$1"; shift || true
+  local command_line="$*"
+  if ! tmux_available; then
+    err "tmux not installed"
+    return 1
+  fi
+  if [[ -z "$session_name" || -z "$command_line" ]]; then
+    err "tmux_send_keys: session and command required"
+    return 1
+  fi
+  tmux send-keys -t "$session_name" -l -- "$command_line" 2>/dev/null || return 1
+  tmux send-keys -t "$session_name" C-m 2>/dev/null || return 1
+}
+
+# Load .env file if it exists
+# Usage: tmux_load_env_file [env_file_path]
+tmux_load_env_file() {
+  local env_file="${1:-$PWD/.env}"
+  if [[ -f "$env_file" ]]; then
+    # Source the .env file, but only export ANTHROPIC_API_KEY
+    set -a  # Auto-export variables
+    source "$env_file"
+    set +a  # Turn off auto-export
+  fi
+}
+
+# Load Anthropic API key from config file or fallback to .env files
+tmux_load_anthropic_api_key() {
+  # First try to load from ~/.orchestra/config.json
+  local config_file="$HOME/.orchestra/config.json"
+  if [[ -f "$config_file" ]] && command -v jq >/dev/null 2>&1; then
+    local api_key
+    api_key="$(jq -r '.anthropic_api_key // empty' "$config_file" 2>/dev/null)"
+    if [[ -n "$api_key" ]] && [[ "$api_key" != "null" ]]; then
+      export ANTHROPIC_API_KEY="$api_key"
+      return 0
+    fi
+  fi
+  
+  # Fallback to .env file loading (existing logic)
+  tmux_load_env_file "$PWD/.env"
+  
+  # If still no API key, try repo root
+  if [[ -z "${ANTHROPIC_API_KEY-}" ]]; then
+    local root
+    root="$(repo_root)"
+    if [[ -n "$root" ]]; then
+      tmux_load_env_file "$root/.env"
+    fi
+  fi
+}
+
+# Generate a descriptive name for a tmux session using AI
+# Usage: tmux_generate_ai_session_name <session_name>
+tmux_generate_ai_session_name() {
+  local session="$1"
+  
+  # Load API key from config file or fallback to .env files
+  tmux_load_anthropic_api_key
+  
+  # Check if ANTHROPIC_API_KEY is set
+  if [[ -z "${ANTHROPIC_API_KEY-}" ]]; then
+    err "ANTHROPIC_API_KEY not found in config file or .env file"
+    return 1
+  fi
+  
+  # Capture the tmux pane content (last 200 lines for better context)
+  local content
+  content="$(tmux capture-pane -t "$session" -p -S -200 2>/dev/null)" || {
+    err "Failed to capture tmux pane content"
+    return 1
+  }
+
+  local pane_cmd
+  pane_cmd="$(tmux display-message -t "$session" -p '#{pane_current_command}' 2>/dev/null || echo "")"
+
+  local history_temp=""
+  local history_arg=""
+  local session_key
+  session_key="$(_orchestra_history_key "$session")"
+  if [[ -n "$session_key" ]]; then
+    local history_dir="${ORCHESTRA_HISTORY_DIR:-$HOME/.orchestra/history}"
+    local history_path="$history_dir/$session_key.log"
+    if [[ -f "$history_path" ]]; then
+      if [[ "$OSTYPE" == "darwin"* ]]; then
+        history_temp=$(mktemp -t gw_hist)
+      else
+        history_temp=$(mktemp)
+      fi
+      tail -n 50 "$history_path" > "$history_temp"
+      history_arg="$history_temp"
+    fi
+  fi
+  
+  # If content is empty or too short, return error
+  if [[ ${#content} -lt 10 ]]; then
+    err "Not enough content to analyze"
+    return 1
+  fi
+  
+  # Truncate content if too long (to stay within token limits)
+  if [[ ${#content} -gt 8000 ]]; then
+    content="${content: -8000}"
+  fi
+  
+  # Create a temporary file for the content to avoid escaping issues
+  # mktemp works differently on macOS vs Linux
+  local temp_file
+  if [[ "$OSTYPE" == "darwin"* ]]; then
+    temp_file=$(mktemp -t gw_tmp)
+  else
+    temp_file=$(mktemp)
+  fi
+  printf '%s' "$content" > "$temp_file"
+  
+  # Prepare the API request using Python for proper JSON encoding
+  local request_body
+  if have_cmd python3; then
+    # Use Python to safely build the request body and extract typed commands from the capture
+    request_body=$(
+      python3 - "$temp_file" "$history_arg" 2>/dev/null <<'PYCODE'
+import json
+import re
+import sys
+from pathlib import Path
+
+temp_path = Path(sys.argv[1])
+content = temp_path.read_text()
+
+lines = content.splitlines()
+command_candidates = []  # Commands captured with high confidence
+fallback_candidates = []  # All prompt-like lines (used if we fail to classify)
+
+history_commands = []
+if len(sys.argv) > 2 and sys.argv[2]:
+    hist_path = Path(sys.argv[2])
+    if hist_path.exists():
+        for line in hist_path.read_text().splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            if "\t" in line:
+                history_commands.append(line.split("\t", 1)[1])
+            else:
+                history_commands.append(line)
+        history_commands = history_commands[-50:]
+
+prompt_pattern = re.compile(r"^[A-Za-z0-9_.@~/-]+$")
+disallowed_prompts = {
+    "warning",
+    "error",
+    "fatal",
+    "hint",
+    "note",
+    "usage",
+    "info",
+    "debug",
+    "trace",
+}
+
+disallowed_first_tokens = {
+    "warning",
+    "error",
+    "fatal",
+    "hint",
+    "note",
+    "usage",
+    "not",
+    "see",
+    "for",
+    "from",
+    "with",
+    "and",
+    "or",
+    "but",
+    "at",
+    "to",
+    "in",
+    "info",
+    "debug",
+    "trace",
+}
+
+common_commands = {
+    "git",
+    "gh",
+    "npm",
+    "pnpm",
+    "yarn",
+    "node",
+    "npx",
+    "bun",
+    "cargo",
+    "go",
+    "python",
+    "python3",
+    "pip",
+    "pip3",
+    "poetry",
+    "pipenv",
+    "pytest",
+    "uvicorn",
+    "gunicorn",
+    "flask",
+    "django-admin",
+    "rails",
+    "bundle",
+    "rake",
+    "mix",
+    "make",
+    "cmake",
+    "gradle",
+    "mvn",
+    "ant",
+    "docker",
+    "docker-compose",
+    "kubectl",
+    "helm",
+    "terraform",
+    "ansible",
+    "ssh",
+    "scp",
+    "rsync",
+    "sftp",
+    "psql",
+    "mysql",
+    "mongo",
+    "redis-cli",
+    "sqlite3",
+    "composer",
+    "php",
+    "ruby",
+    "java",
+    "javac",
+    "deno",
+    "dotnet",
+    "msbuild",
+    "tsc",
+    "nx",
+    "lerna",
+    "eslint",
+    "prettier",
+    "ls",
+    "cd",
+    "pwd",
+    "cat",
+    "tail",
+    "head",
+    "less",
+    "more",
+    "grep",
+    "rg",
+    "fd",
+    "find",
+    "watch",
+    "code",
+    "open",
+    "vim",
+    "nvim",
+    "tmux",
+    "htop",
+    "top",
+    "brew",
+    "tox",
+}
+
+allowed_prefixes = (
+    "./",
+    "../",
+    "~/",
+    "bin/",
+    "sbin/",
+)
+
+
+def clean_tokens(tokens):
+    while tokens and tokens[0] in {"$", "#", "%"}:
+        tokens = tokens[1:]
+    return tokens
+
+
+for raw_line in lines:
+    stripped = raw_line.strip()
+    if not stripped or ":" not in stripped:
+        continue
+
+    prompt_part, command_part = stripped.split(":", 1)
+    prompt_part = prompt_part.strip().rstrip("#$%")
+    command_part = command_part.strip()
+
+    if not prompt_part or not command_part:
+        continue
+
+    if not prompt_pattern.match(prompt_part):
+        continue
+
+    prompt_lower = prompt_part.lower()
+    if prompt_lower in disallowed_prompts:
+        continue
+
+    tokens = clean_tokens(command_part.split())
+    if not tokens:
+        continue
+
+    first_token = tokens[0].lower()
+    if first_token == "sudo" and len(tokens) > 1:
+        first_token = tokens[1].lower()
+
+    if first_token in disallowed_first_tokens:
+        continue
+
+    normalized_command = " ".join(tokens)
+    formatted_line = f"{prompt_part}:{normalized_command}"
+    fallback_candidates.append(formatted_line)
+
+    allowed = (
+        first_token in common_commands
+        or normalized_command.startswith(allowed_prefixes)
+        or any(
+            first_token.startswith(prefix)
+            for prefix in (
+                "git",
+                "npm",
+                "pnpm",
+                "yarn",
+                "node",
+                "npx",
+                "bun",
+                "cargo",
+                "python",
+                "pip",
+                "poetry",
+                "pytest",
+                "uvicorn",
+                "docker",
+                "kubectl",
+                "helm",
+                "terraform",
+                "ansible",
+                "ssh",
+                "scp",
+                "rsync",
+                "rails",
+                "bundle",
+                "rake",
+                "mix",
+                "psql",
+                "mysql",
+                "mongo",
+                "redis",
+            )
+        )
+    )
+
+    if allowed:
+        command_candidates.append(formatted_line)
+
+
+if history_commands:
+    command_candidates = history_commands
+elif not command_candidates:
+    command_candidates = fallback_candidates
+
+extracted_commands = command_candidates
+history_lines = [f"{idx + 1}. {line}" for idx, line in enumerate(extracted_commands)]
+command_history = "\n".join(history_lines) if history_lines else "None detected."
+last_command_line = extracted_commands[-1] if extracted_commands else ""
+commands_detected = bool(extracted_commands)
+
+# Capture the first 10 lines of output as fallback context (joined by newline)
+first_ten_lines = "\n".join(lines[:10]) if lines else ""
+
+prefix_guidance = """Prefix selection rules based on the most recent command:
+- git_* : git or gh commands, or any git-related activity
+- opencode_* : Claude Code, OpenCode, Cursor, or similar AI coding tools
+- running_* : Commands that start dev servers (npm/yarn/pnpm run dev, uvicorn, next dev, etc.)
+- build_* : Build/compile steps (npm/yarn/pnpm run build, cargo build, make, webpack, etc.)
+- test_* : Unit/integration tests (npm test, pytest, jest, go test, cargo test, etc.)
+- docker_* : Docker or container tooling (docker, docker-compose, kubectl, helm)
+- ssh_* : SSH, scp, rsync, or remote shell connections
+- db_* : Database work (psql, mysql, mongo, redis-cli, migrations)
+- debug_* : Explicit debugging or error triage commands
+- deploy_* : Deployment or release related commands
+- Otherwise derive a concise descriptive prefix from the command context.
+When multiple categories match, prioritize git_ > docker_ > running_ > build_ > test_ > deploy_ > debug_ > db_ > ssh_ > opencode_."""
+
+prompt = f"""Analyze this terminal session and create a descriptive tmux session name based on what the user actually did.
+
+Terminal output (last capture):
+{content}
+
+Extracted command history (oldest to newest):
+{command_history}
+
+Most recent command (anchor for app prefix and summary):
+{last_command_line if last_command_line else 'None detected'}
+
+Focus: use the most recent command to determine the application prefix and primary activity description. Map it according to these rules:
+{prefix_guidance}
+
+{'No clear prompt/command lines were detected. Rely on the terminal output context.' if not commands_detected else ''}
+
+{'First 10 lines of terminal output (useful for identifying running app/service):\n' + first_ten_lines if not commands_detected and first_ten_lines else ''}
+
+If no commands were detected, fall back to terminal output analysis but describe the main activity in the name. Identify the dominant application or process implied by the output (e.g., web server, test runner, build tool).
+
+Instructions:
+1. Produce a session name using lowercase letters, numbers, and underscores only.
+2. Maximum length: 100 characters.
+3. Include an app/activity prefix derived from the most recent command (see rules above).
+4. Describe the concrete task or state in a short phrase after the prefix.
+5. If git activity is visible anywhere, the prefix MUST be git_.
+6. Respond with ONLY the final session name, nothing else."""
+
+request = {
+    "model": "claude-3-5-haiku-latest",
+    "max_tokens": 100,
+    "messages": [
+        {
+            "role": "user",
+            "content": prompt
+        }
+    ]
+}
+
+print(json.dumps(request))
+PYCODE
+    )
+  else
+    # Fallback: base64 encode the content to avoid escaping issues
+    local encoded_content=$(base64 < "$temp_file" | tr -d '\n')
+    request_body=$(cat <<EOF
+{
+  "model": "claude-3-5-haiku-latest",
+  "max_tokens": 100,
+  "messages": [
+    {
+      "role": "user",
+      "content": "I'll send you base64-encoded terminal output. Please decode it, analyze it, and create a descriptive name for this tmux session.\n\nIMPORTANT: Ignore any window titles or metadata. Focus ONLY on the actual terminal content.\n\nCRITICAL: Check for Git patterns FIRST:\n- Git commands: git status, diff, add, commit, push, pull, checkout, branch, merge, rebase, log, stash\n- Git output: 'On branch', 'Changes not staged', 'modified:', 'new file:', diff output (+/-/@@), commit hashes\n- If ANY Git patterns found, use 'git_' prefix (highest priority)\n\nOther prefixes:\n- opencode_: AI coding tools (Claude Code, OpenCode, Cursor)\n- running_: Dev servers (npm run dev, yarn dev)\n- ssh_: SSH connections\n- docker_: Docker/container operations\n- build_: Build processes\n- test_: Testing\n- db_: Database operations\n\nUse underscores only. Max 100 chars total.\n\nExamples:\n- git_reviewing_changes_before_commit\n- git_resolving_merge_conflicts\n- opencode_fixing_auth_bug\n- running_nextjs_dev_server\n\nBase64 terminal output:\n${encoded_content}\n\nRespond with ONLY the session name, nothing else."
+    }
+  ]
+}
+EOF
+    )
+  fi
+  
+  # Clean up temp file
+  rm -f "$temp_file"
+  if [[ -n "$history_temp" ]]; then
+    rm -f "$history_temp"
+  fi
+  
+  # Make the API call
+  local response
+  response=$(curl -s -X POST https://api.anthropic.com/v1/messages \
+    --max-time 20 \
+    -H "Content-Type: application/json" \
+    -H "x-api-key: $ANTHROPIC_API_KEY" \
+    -H "anthropic-version: 2023-06-01" \
+    -d "$request_body" 2>&1) || {
+    err "Failed to call Anthropic API: $response"
+    return 1
+  }
+  
+  # Check if response contains an error
+  if echo "$response" | grep -q '"error"'; then
+    local error_msg=$(echo "$response" | python3 -c "import sys, json; print(json.load(sys.stdin).get('error', {}).get('message', 'Unknown error'))" 2>/dev/null || echo "API error")
+    err "API error: $error_msg"
+    return 1
+  fi
+  
+  # Extract the content from the response
+  local new_name
+  new_name=$(echo "$response" | python3 -c "import sys, json; data = json.load(sys.stdin); print(data.get('content', [{}])[0].get('text', ''))" 2>/dev/null) || {
+    # Fallback to grep method if python fails
+    new_name=$(echo "$response" | grep -o '"text":"[^"]*"' | head -1 | sed 's/"text":"\([^"]*\)"/\1/')
+  }
+  
+  # Clean up the name (remove any spaces, special chars except underscore and dash)
+  new_name=$(echo "$new_name" | tr ' ' '_' | sed 's/[^a-zA-Z0-9_-]//g' | cut -c1-100)
+
+  # Derive an override prefix from the active pane command (if available)
+  local override_prefix=""
+  if [[ -n "$pane_cmd" ]]; then
+    override_prefix="${pane_cmd##*/}"
+    override_prefix="${override_prefix%% *}"
+    override_prefix=$(echo "$override_prefix" | tr '[:upper:]' '[:lower:]')
+    override_prefix=$(echo "$override_prefix" | tr -c 'a-z0-9' '_')
+    override_prefix="${override_prefix//__/_}"
+    override_prefix="${override_prefix##_}"
+    override_prefix="${override_prefix%%_}"
+  fi
+
+  case "$override_prefix" in
+    ""|"bash"|"zsh"|"sh"|"fish"|"tmux"|"login"|"sudo"|"man"|"less"|"more"|"cat"|"tail"|"watch")
+      override_prefix=""
+      ;;
+  esac
+
+  if [[ -n "$override_prefix" ]]; then
+    local current_prefix rest
+    current_prefix="${new_name%%_*}"
+    if [[ "$new_name" == *_* ]]; then
+      rest="${new_name#*_}"
+    else
+      rest="$new_name"
+    fi
+    if [[ -z "$rest" || "$rest" == "$override_prefix" ]]; then
+      rest="session_activity"
+    fi
+    if [[ "$current_prefix" != "$override_prefix" ]]; then
+      new_name="${override_prefix}_${rest}"
+    fi
+  fi
+
+  new_name=$(echo "$new_name" | tr ' ' '_' | sed 's/[^a-zA-Z0-9_-]//g' | cut -c1-100)
+  
+  if [[ -z "$new_name" ]]; then
+    err "Failed to generate name from AI response"
+    return 1
+  fi
+  
+  echo "$new_name"
+}
+
+# Display tmux message
+# Usage: tmux_display_message <message> [duration_ms]
+tmux_display_message() {
+  local message="$1"
+  local duration="${2:-3000}"
+  
+  if tmux_available && tmux_inside_session; then
+    tmux display-message -d "$duration" "$message"
+  fi
+}