@humanu/orchestra 0.5.71 → 0.5.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanu/orchestra",
-  "version": "0.5.71",
+  "version": "0.5.72",
   "description": "AI-powered Git worktree and tmux session manager with modern TUI",
   "keywords": [
     "git",

package/resources/api/tmux.sh

@@ -236,18 +236,330 @@ _tmux_source_command_hook() {
 # Helper: orchestra prefix including delimiter
 _tmux_orch_prefix() { printf "orchestra%s" "$( _tmux_delim )"; }
 
+_tmux_session_registry_path() {
+  if [[ -n "${ORCHESTRA_SESSION_REGISTRY_PATH-}" ]]; then
+    printf '%s\n' "$ORCHESTRA_SESSION_REGISTRY_PATH"
+    return
+  fi
+  printf '%s\n' "$HOME/.orchestra/orchestra.sqlite3"
+}
+
+_tmux_shared_root_for_path() {
+  local path="$1"
+  local old_pwd="$PWD"
+  local root=""
+  if [[ -n "$path" && -d "$path" ]]; then
+    cd "$path" 2>/dev/null || return 1
+    root="$(git_shared_root 2>/dev/null || git_repo_root 2>/dev/null || true)"
+    cd "$old_pwd" 2>/dev/null || true
+  fi
+  [[ -n "$root" ]] || return 1
+  printf '%s\n' "$root"
+}
+
+_tmux_branch_for_path() {
+  local path="$1"
+  local old_pwd="$PWD"
+  local branch=""
+  if [[ -n "$path" && -d "$path" ]]; then
+    cd "$path" 2>/dev/null || return 1
+    branch="$(git_current_branch 2>/dev/null || true)"
+    cd "$old_pwd" 2>/dev/null || true
+  fi
+  [[ -n "$branch" ]] || return 1
+  printf '%s\n' "$branch"
+}
+
+_tmux_registry_upsert_session() {
+  local repo_root="$1"
+  local branch="$2"
+  local worktree_path="$3"
+  local tmux_name="$4"
+  local db_path
+  db_path="$(_tmux_session_registry_path)"
+
+  [[ -n "$repo_root" && -n "$branch" && -n "$worktree_path" && -n "$tmux_name" ]] || return 1
+  have_cmd python3 || return 1
+
+  python3 - "$db_path" "$repo_root" "$branch" "$worktree_path" "$tmux_name" <<'PY'
+import os
+import sqlite3
+import sys
+import time
+
+db_path, repo_root, branch, worktree_path, tmux_name = sys.argv[1:6]
+os.makedirs(os.path.dirname(db_path), exist_ok=True)
+slug = branch.replace("/", "-")
+now = int(time.time())
+
+conn = sqlite3.connect(db_path)
+conn.execute(
+    """
+    CREATE TABLE IF NOT EXISTS sessions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        tmux_name TEXT NOT NULL UNIQUE,
+        repo_root TEXT NOT NULL,
+        worktree_path TEXT NOT NULL,
+        branch TEXT NOT NULL,
+        slug TEXT NOT NULL,
+        display_name TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        last_seen_at INTEGER NOT NULL
+    )
+    """
+)
+conn.execute(
+    "CREATE INDEX IF NOT EXISTS idx_sessions_worktree ON sessions(repo_root, worktree_path)"
+)
+conn.execute("CREATE INDEX IF NOT EXISTS idx_sessions_slug ON sessions(repo_root, slug)")
+conn.execute(
+    """
+    INSERT INTO sessions (
+        tmux_name, repo_root, worktree_path, branch, slug,
+        created_at, updated_at, last_seen_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?6, ?6)
+    ON CONFLICT(tmux_name) DO UPDATE SET
+        repo_root = excluded.repo_root,
+        worktree_path = excluded.worktree_path,
+        branch = excluded.branch,
+        slug = excluded.slug,
+        updated_at = excluded.updated_at,
+        last_seen_at = excluded.last_seen_at
+    """,
+    (tmux_name, repo_root, worktree_path, branch, slug, now),
+)
+conn.commit()
+PY
+}
+
+_tmux_registry_rename_session() {
+  local old_tmux_name="$1"
+  local new_tmux_name="$2"
+  local display_name="${3:-}"
+  local db_path
+  db_path="$(_tmux_session_registry_path)"
+
+  [[ -f "$db_path" ]] || return 0
+  have_cmd python3 || return 1
+
+  python3 - "$db_path" "$old_tmux_name" "$new_tmux_name" "$display_name" <<'PY'
+import sqlite3
+import sys
+import time
+
+db_path, old_tmux_name, new_tmux_name, display_name = sys.argv[1:5]
+now = int(time.time())
+value = display_name if display_name else None
+
+conn = sqlite3.connect(db_path)
+conn.execute(
+    """
+    UPDATE sessions
+    SET tmux_name = ?1,
+        display_name = COALESCE(?2, display_name),
+        updated_at = ?3,
+        last_seen_at = ?3
+    WHERE tmux_name = ?4
+    """,
+    (new_tmux_name, value, now, old_tmux_name),
+)
+conn.commit()
+PY
+}
+
+_tmux_registry_remove_session() {
+  local tmux_name="$1"
+  local db_path
+  db_path="$(_tmux_session_registry_path)"
+
+  [[ -f "$db_path" ]] || return 0
+  have_cmd python3 || return 1
+
+  python3 - "$db_path" "$tmux_name" <<'PY'
+import sqlite3
+import sys
+
+db_path, tmux_name = sys.argv[1:3]
+conn = sqlite3.connect(db_path)
+conn.execute("DELETE FROM sessions WHERE tmux_name = ?1", (tmux_name,))
+conn.commit()
+PY
+}
+
+_tmux_registry_upsert_current_session() {
+  local session_name="$1"
+  local session_dir repo_root branch
+  session_dir="$(tmux display-message -t "$session_name" -p '#{pane_current_path}' 2>/dev/null || echo "")"
+  repo_root="$(_tmux_shared_root_for_path "$session_dir" 2>/dev/null || true)"
+  branch="$(_tmux_branch_for_path "$session_dir" 2>/dev/null || true)"
+  [[ -n "$repo_root" && -n "$branch" ]] || return 1
+  _tmux_registry_upsert_session "$repo_root" "$branch" "$session_dir" "$session_name"
+}
+
+_tmux_registry_sync_active_workspace_sessions() {
+  local repo_root="$1"
+  [[ -n "$repo_root" ]] || return 1
+  tmux_available || return 1
+
+  local session_name session_dir session_root branch display_name
+  while IFS= read -r session_name; do
+    [[ -n "$session_name" ]] || continue
+    display_name="$(tmux show-option -t "$session_name" -qv @orchestra_display_name 2>/dev/null || true)"
+    [[ -n "$display_name" ]] || continue
+    session_dir="$(tmux display-message -t "$session_name" -p '#{pane_current_path}' 2>/dev/null || echo "")"
+    session_root="$(_tmux_shared_root_for_path "$session_dir" 2>/dev/null || true)"
+    [[ "$session_root" == "$repo_root" ]] || continue
+    branch="$(_tmux_branch_for_path "$session_dir" 2>/dev/null || true)"
+    [[ -n "$branch" ]] || continue
+    _tmux_registry_upsert_session "$repo_root" "$branch" "$session_dir" "$session_name" >/dev/null 2>&1 || true
+  done < <(tmux list-sessions -F '#{session_name}' 2>/dev/null || true)
+}
+
 _tmux_status_escape_text() {
   local text="$1"
   text="${text//\#/##}"
   printf '%s' "$text"
 }
 
+_tmux_truncate_tab_label() {
+  local label="$1"
+  local max_len="${2:-18}"
+  if (( ${#label} > max_len )); then
+    printf '%s...' "${label:0:$((max_len - 3))}"
+  else
+    printf '%s' "$label"
+  fi
+}
+
+_tmux_workspace_session_rows() {
+  local current_session="$1"
+  local repo_root="$2"
+  local db_path active_file
+  db_path="$(_tmux_session_registry_path)"
+
+  [[ -f "$db_path" ]] || return 0
+  have_cmd python3 || return 0
+
+  active_file="$(mktemp)"
+  tmux list-sessions -F '#{session_name}' > "$active_file" 2>/dev/null || {
+    rm -f "$active_file"
+    return 0
+  }
+
+  python3 - "$db_path" "$repo_root" "$current_session" "$active_file" <<'PY'
+import sqlite3
+import sys
+
+db_path, repo_root, current_session, active_path = sys.argv[1:5]
+with open(active_path, "r", encoding="utf-8") as handle:
+    active = {line.strip() for line in handle if line.strip()}
+
+conn = sqlite3.connect(db_path)
+rows = conn.execute(
+    """
+    SELECT tmux_name, COALESCE(display_name, '')
+    FROM sessions
+    WHERE repo_root = ?1
+    ORDER BY worktree_path COLLATE NOCASE, created_at, tmux_name COLLATE NOCASE
+    """,
+    (repo_root,),
+).fetchall()
+
+filtered = []
+seen = set()
+for name, display_name in rows:
+    if name in active and name not in seen:
+        filtered.append((name, display_name or ""))
+        seen.add(name)
+
+if not filtered:
+    raise SystemExit(0)
+
+max_tabs = 8
+if len(filtered) <= max_tabs:
+    visible = filtered
+    prefix = suffix = False
+else:
+    try:
+        current_index = [name for name, _ in filtered].index(current_session)
+    except ValueError:
+        current_index = 0
+    start = max(0, min(current_index - 2, len(filtered) - max_tabs))
+    end = min(len(filtered), start + max_tabs)
+    visible = filtered[start:end]
+    prefix = start > 0
+    suffix = end < len(filtered)
+
+if prefix:
+    print("__ellipsis__\t")
+for name, display_name in visible:
+    print(f"{name}\t{display_name}")
+if suffix:
+    print("__ellipsis__\t")
+PY
+  local status=$?
+  rm -f "$active_file"
+  return $status
+}
+
+_tmux_workspace_session_tabs() {
+  local current_session="$1"
+  local fallback_display_name="$2"
+  local session_dir repo_root rows tabs name display_name label escaped_label divider
+
+  session_dir="$(tmux display-message -t "$current_session" -p '#{pane_current_path}' 2>/dev/null || echo "")"
+  repo_root="$(_tmux_shared_root_for_path "$session_dir" 2>/dev/null || true)"
+  if [[ -n "$repo_root" ]]; then
+    _tmux_registry_sync_active_workspace_sessions "$repo_root" >/dev/null 2>&1 || true
+    rows="$(_tmux_workspace_session_rows "$current_session" "$repo_root" 2>/dev/null || true)"
+  else
+    rows=""
+  fi
+
+  if [[ -z "$rows" ]]; then
+    label="$(_tmux_truncate_tab_label "$fallback_display_name")"
+    escaped_label="$(_tmux_status_escape_text "$label")"
+    printf '#[fg=white,bg=colour22,bold] %s #[default]' "$escaped_label"
+    return
+  fi
+
+  tabs=""
+  divider="#[fg=white,bg=colour22] | #[default]"
+  while IFS=$'\t' read -r name display_name; do
+    [[ -n "$name" ]] || continue
+    if [[ -n "$tabs" ]]; then
+      tabs+="$divider"
+    fi
+    if [[ "$name" == "__ellipsis__" ]]; then
+      tabs+="#[fg=white,bg=colour22]  ...  #[default]"
+      continue
+    fi
+
+    if [[ -z "$display_name" ]]; then
+      display_name="$(tmux_format_session_display "$name" without-timestamp)"
+    fi
+    label="$(_tmux_truncate_tab_label "$display_name")"
+    escaped_label="$(_tmux_status_escape_text "$label")"
+
+    if [[ "$name" == "$current_session" ]]; then
+      tabs+="#[fg=white,bg=colour22,bold]  [${escaped_label}]  #[default]"
+    else
+      tabs+="#[fg=white,bg=colour22]  ${escaped_label}  #[default]"
+    fi
+  done <<< "$rows"
+
+  printf '%s' "$tabs"
+}
+
 _tmux_orchestra_status_left() {
-  local worktree_name="$1"
-  local session_display_name="$2"
-  worktree_name="$(_tmux_status_escape_text "$worktree_name")"
-  session_display_name="$(_tmux_status_escape_text "$session_display_name")"
-  printf '#[fg=white,bg=colour22,bold] %s #[default] Rename: Ctrl+b,r | Go back (detach): Ctrl+b,d | Copy (scroll) mode: Ctrl+b,[ | Worktree: %s' "$session_display_name" "$worktree_name"
+  local session_name="$1"
+  local session_display_name="$3"
+  _tmux_workspace_session_tabs "$session_name" "$session_display_name"
+}
+
+_tmux_orchestra_status_right() {
+  printf ''
 }
 
 _tmux_configure_orchestra_bindings() {
@@ -255,32 +567,78 @@ _tmux_configure_orchestra_bindings() {
   bridge="$(_orchestra_bridge_script)"
   [[ -f "$bridge" ]] || return
 
-  local quoted_bridge rename_command prompt_command
+  local quoted_bridge rename_command prompt_command next_command previous_command help_command
   printf -v quoted_bridge '%q' "$bridge"
   rename_command="$quoted_bridge manual-rename-session \\\"#{session_name}\\\" \\\"%%\\\" >/dev/null 2>&1"
   prompt_command="command-prompt -p 'Rename Orchestra session:' 'run-shell -b \"$rename_command\"'"
+  next_command="$quoted_bridge cycle-workspace-session \\\"#{session_name}\\\" next \\\"#{client_tty}\\\" >/dev/null 2>&1"
+  previous_command="$quoted_bridge cycle-workspace-session \\\"#{session_name}\\\" previous \\\"#{client_tty}\\\" >/dev/null 2>&1"
+  help_command="$quoted_bridge tmux-help-popup \\\"#{client_tty}\\\" >/dev/null 2>&1"
 
+  tmux bind-key -T prefix '?' if-shell -F '#{@orchestra_display_name}' \
+    "run-shell -b \"$help_command\"" 'list-keys -N' >/dev/null 2>&1 || true
   tmux bind-key -T prefix r if-shell -F '#{@orchestra_display_name}' \
     "$prompt_command" 'refresh-client -S' >/dev/null 2>&1 || true
+  tmux bind-key -T prefix '>' if-shell -F '#{@orchestra_display_name}' \
+    "run-shell -b \"$next_command\"" 'switch-client -n' >/dev/null 2>&1 || true
+  tmux bind-key -T prefix '<' if-shell -F '#{@orchestra_display_name}' \
+    "run-shell -b \"$previous_command\"" 'switch-client -p' >/dev/null 2>&1 || true
+  tmux bind-key -r -T prefix Right if-shell -F '#{@orchestra_display_name}' \
+    "run-shell -b \"$next_command\"" 'select-pane -R' >/dev/null 2>&1 || true
+  tmux bind-key -r -T prefix Left if-shell -F '#{@orchestra_display_name}' \
+    "run-shell -b \"$previous_command\"" 'select-pane -L' >/dev/null 2>&1 || true
 }
 
 _tmux_configure_orchestra_status() {
   local session_name="$1"
   local worktree_name="$2"
   local session_display_name="${3:-}"
-  local status_left
+  local status_left status_right
   if [[ -z "$session_display_name" ]]; then
     session_display_name="$(tmux_format_session_display "$session_name" without-timestamp)"
   fi
-  status_left="$(_tmux_orchestra_status_left "$worktree_name" "$session_display_name")"
+  status_left="$(_tmux_orchestra_status_left "$session_name" "$worktree_name" "$session_display_name")"
+  status_right="$(_tmux_orchestra_status_right "$worktree_name")"
 
   tmux set-option -t "$session_name" @orchestra_display_name "$session_display_name" >/dev/null 2>&1 || true
   tmux set-option -t "$session_name" @orchestra_worktree_name "$worktree_name" >/dev/null 2>&1 || true
+  tmux set-option -t "$session_name" status on >/dev/null 2>&1 || true
+  tmux set-option -t "$session_name" status-position bottom >/dev/null 2>&1 || true
   tmux set-option -t "$session_name" status-left "$status_left" >/dev/null 2>&1 || true
-  tmux set-option -t "$session_name" status-left-length 220 >/dev/null 2>&1 || true
+  tmux set-option -t "$session_name" status-left-length 1000 >/dev/null 2>&1 || true
+  tmux set-option -t "$session_name" status-right "$status_right" >/dev/null 2>&1 || true
+  tmux set-option -t "$session_name" status-right-length 0 >/dev/null 2>&1 || true
+  tmux set-option -t "$session_name" window-status-format "" >/dev/null 2>&1 || true
+  tmux set-option -t "$session_name" window-status-current-format "" >/dev/null 2>&1 || true
+  tmux set-option -t "$session_name" window-status-separator "" >/dev/null 2>&1 || true
   _tmux_configure_orchestra_bindings
 }
 
+_tmux_refresh_orchestra_session_status() {
+  local session_name="$1"
+  local session_dir branch_name worktree_name display_name old_pwd
+
+  session_dir="$(tmux display-message -t "$session_name" -p '#{pane_current_path}' 2>/dev/null || echo "")"
+  branch_name=""
+  if [[ -n "$session_dir" && -d "$session_dir" ]]; then
+    old_pwd="$PWD"
+    cd "$session_dir" 2>/dev/null || true
+    branch_name="$(git_current_branch 2>/dev/null || git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+    cd "$old_pwd" 2>/dev/null || true
+  fi
+
+  if [[ -n "$branch_name" && "$branch_name" != "detached" ]]; then
+    worktree_name="$branch_name"
+  elif [[ -n "$session_dir" && -d "$session_dir" ]]; then
+    worktree_name="$(basename "$session_dir")"
+  else
+    worktree_name="$branch_name"
+  fi
+
+  display_name="$(tmux show-option -t "$session_name" -qv @orchestra_display_name 2>/dev/null || true)"
+  _tmux_configure_orchestra_status "$session_name" "$worktree_name" "$display_name"
+}
+
 # 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() {
@@ -355,14 +713,20 @@ tmux_create_session() {
   # Get repository info from the working directory context
   local repo_name=""
   local branch_name=""
+  local repo_root=""
   local old_pwd="$PWD"
+  local resolved_working_dir="$working_dir"
+  if [[ -n "$working_dir" && -d "$working_dir" ]]; then
+    resolved_working_dir="$(cd "$working_dir" 2>/dev/null && pwd -P || printf '%s' "$working_dir")"
+  fi
   
   # Change to working directory to get accurate git info
-  cd "$working_dir" 2>/dev/null || true
+  cd "$resolved_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")"
+    repo_root="$(git_shared_root 2>/dev/null || git_repo_root 2>/dev/null || true)"
   fi
   
   # Restore original directory
@@ -376,21 +740,24 @@ tmux_create_session() {
   fi
   
   # Create session with custom Orchestra status configuration
-  tmux new-session -Ad -s "$session_name" -c "$working_dir" >/dev/null 2>&1 || {
+  tmux new-session -Ad -s "$session_name" -c "$resolved_working_dir" >/dev/null 2>&1 || {
     err "Failed to create tmux session: $session_name"
     return 1
   }
   
+  local worktree_name=""
+  if [[ -n "$branch_name" && "$branch_name" != "detached" ]]; then
+    worktree_name="$branch_name"
+  else
+    worktree_name="$(basename "$resolved_working_dir")"
+  fi
+
+  if [[ -n "$repo_root" && -n "$branch_name" && "$branch_name" != "detached" ]]; then
+    _tmux_registry_upsert_session "$repo_root" "$branch_name" "$resolved_working_dir" "$session_name" >/dev/null 2>&1 || true
+  fi
+
   # 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_configure_orchestra_status "$session_name" "$worktree_name"
   fi
   
@@ -467,6 +834,7 @@ tmux_kill_session() {
     err "Failed to kill session: $session_name"
     return 1
   }
+  _tmux_registry_remove_session "$session_name" >/dev/null 2>&1 || true
 }
 
 # Attach or switch to session
@@ -519,19 +887,7 @@ tmux_attach_session() {
       "🎼 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_configure_orchestra_status "$sess" "$worktree_name"
+  _tmux_refresh_orchestra_session_status "$sess"
   
   if tmux_inside_session; then
     tmux switch-client -t "$sess" >/dev/null 2>&1 || true
@@ -609,6 +965,7 @@ tmux_rename_session() {
     err "Failed to rename session"
     return 1
   }
+  _tmux_registry_rename_session "$old_session" "$new_session" "$(format_session_display_name "$new_name")" >/dev/null 2>&1 || true
   local worktree_name
   worktree_name="$(tmux show-option -t "$new_session" -qv @orchestra_worktree_name 2>/dev/null || true)"
   if [[ -z "$worktree_name" ]]; then
@@ -1044,6 +1401,157 @@ tmux_send_keys() {
   tmux send-keys -t "$session_name" C-m 2>/dev/null || return 1
 }
 
+# Show Orchestra tmux shortcuts in a popup modal.
+# Usage: tmux_show_orchestra_help_popup [client_tty]
+tmux_show_orchestra_help_popup() {
+  local target_client="${1:-}"
+  if ! tmux_available; then
+    err "tmux not installed"
+    return 1
+  fi
+
+  local target_args=()
+  if [[ -n "$target_client" ]]; then
+    target_args=(-c "$target_client")
+  fi
+
+  local popup_command
+  popup_command='printf "%s\n" \
+"Orchestra tmux shortcuts" \
+"" \
+"Ctrl+b, Left      Previous Orchestra session in this workspace" \
+"Ctrl+b, Right     Next Orchestra session in this workspace" \
+"Ctrl+b, <         Previous Orchestra session in this workspace" \
+"Ctrl+b, >         Next Orchestra session in this workspace" \
+"Ctrl+b, r         Rename the current Orchestra session" \
+"Ctrl+b, d         Detach and return to Orchestra" \
+"Ctrl+b, [         Copy/scroll mode" \
+"Ctrl+b, ?         Show this help" \
+"" \
+"Press Enter to close..."; read -r _'
+
+  tmux display-popup "${target_args[@]}" -E -w 78 -h 15 -T "Orchestra shortcuts" "$popup_command" >/dev/null 2>&1
+}
+
+# Find the adjacent active Orchestra session registered for the current repo.
+# Usage: tmux_workspace_cycle_target <current_session> <next|previous>
+tmux_workspace_cycle_target() {
+  local current_session="$1"
+  local direction="$2"
+  local session_dir repo_root db_path active_file target
+
+  if ! tmux_available; then
+    err "tmux not installed"
+    return 1
+  fi
+  if [[ -z "$current_session" ]]; then
+    err "tmux_workspace_cycle_target: current session required"
+    return 1
+  fi
+  case "$direction" in
+    next|previous|prev) ;;
+    *)
+      err "tmux_workspace_cycle_target: direction must be next or previous"
+      return 1
+      ;;
+  esac
+
+  _tmux_registry_upsert_current_session "$current_session" >/dev/null 2>&1 || true
+
+  session_dir="$(tmux display-message -t "$current_session" -p '#{pane_current_path}' 2>/dev/null || echo "")"
+  repo_root="$(_tmux_shared_root_for_path "$session_dir" 2>/dev/null || true)"
+  if [[ -z "$repo_root" ]]; then
+    err "Unable to determine Orchestra workspace for session"
+    return 1
+  fi
+  _tmux_registry_sync_active_workspace_sessions "$repo_root" >/dev/null 2>&1 || true
+
+  db_path="$(_tmux_session_registry_path)"
+  if [[ ! -f "$db_path" ]]; then
+    err "No Orchestra session registry found"
+    return 1
+  fi
+  have_cmd python3 || {
+    err "python3 is required to read the Orchestra session registry"
+    return 1
+  }
+
+  active_file="$(mktemp)"
+  tmux list-sessions -F '#{session_name}' > "$active_file" 2>/dev/null || {
+    rm -f "$active_file"
+    err "Unable to list tmux sessions"
+    return 1
+  }
+
+  target="$(python3 - "$db_path" "$repo_root" "$current_session" "$direction" "$active_file" <<'PY'
+import sqlite3
+import sys
+
+db_path, repo_root, current_session, direction, active_path = sys.argv[1:6]
+with open(active_path, "r", encoding="utf-8") as handle:
+    active = {line.strip() for line in handle if line.strip()}
+
+conn = sqlite3.connect(db_path)
+rows = conn.execute(
+    """
+    SELECT tmux_name
+    FROM sessions
+    WHERE repo_root = ?1
+    ORDER BY worktree_path COLLATE NOCASE, created_at, tmux_name COLLATE NOCASE
+    """,
+    (repo_root,),
+).fetchall()
+
+names = []
+seen = set()
+for (name,) in rows:
+    if name in active and name not in seen:
+        names.append(name)
+        seen.add(name)
+
+if len(names) < 2 or current_session not in seen:
+    raise SystemExit(0)
+
+index = names.index(current_session)
+if direction == "next":
+    index = (index + 1) % len(names)
+else:
+    index = (index - 1) % len(names)
+print(names[index])
+PY
+  )"
+  local query_status=$?
+  rm -f "$active_file"
+  if [[ $query_status -ne 0 ]]; then
+    err "Unable to query Orchestra session registry"
+    return 1
+  fi
+  [[ -n "$target" ]] || return 1
+  printf '%s\n' "$target"
+}
+
+# Switch the current tmux client to an adjacent registered Orchestra session.
+# Usage: tmux_cycle_workspace_session <current_session> <next|previous> [client_tty]
+tmux_cycle_workspace_session() {
+  local current_session="$1"
+  local direction="$2"
+  local target_client="${3:-}"
+  local target_session
+
+  if ! target_session="$(tmux_workspace_cycle_target "$current_session" "$direction")"; then
+    tmux display-message -d 2500 "No other Orchestra sessions in this workspace" 2>/dev/null || true
+    return 1
+  fi
+
+  _tmux_refresh_orchestra_session_status "$target_session" >/dev/null 2>&1 || true
+
+  if [[ -n "$target_client" ]]; then
+    tmux switch-client -c "$target_client" -t "$target_session" >/dev/null 2>&1 || return 1
+  else
+    tmux switch-client -t "$target_session" >/dev/null 2>&1 || return 1
+  fi
+}
+
 # Load .env file if it exists
 # Usage: tmux_load_env_file [env_file_path]
 tmux_load_env_file() {

package/resources/scripts/gw-bridge.sh

@@ -109,6 +109,14 @@ case "${1:-}" in
   "tmux-send-keys")
     bridge_tmux_send_keys "${2:-}" "${@:3}"
     ;;
+
+  "cycle-workspace-session")
+    bridge_cycle_workspace_session "${2:-}" "${3:-}" "${4:-}"
+    ;;
+
+  "tmux-help-popup")
+    bridge_tmux_help_popup "${2:-}"
+    ;;
     
   "session-metadata")
     bridge_session_metadata "${2:-}"
@@ -233,6 +241,9 @@ Commands:
   delete-branch-only <branch>       Delete branch only (keep worktree)
   switch-worktree <path>            Generate cd command for path
   copy-env-files <source> <target>  Copy .env files between directories
+  cycle-workspace-session <session> <next|previous> [client]
+                                    Switch within registered Orchestra sessions for this repo
+  tmux-help-popup [client]          Show Orchestra tmux shortcut popup
   repo-info                         Get repository information
   git-status                        Get git status --porcelain
   enhanced-git-status [dir]         Get enhanced git status with file stats and line counts

package/resources/scripts/shell/bridge/tmux.sh

@@ -112,6 +112,42 @@ bridge_tmux_send_keys() {
   fi
 }
 
+# Cycle to next/previous registered Orchestra session in the current workspace
+bridge_cycle_workspace_session() {
+  if [[ -z "${1:-}" ]] || [[ -z "${2:-}" ]]; then
+    json_error "Session name and direction required"
+    return 1
+  fi
+  session_name="$1"
+  direction="$2"
+  target_client="${3:-}"
+
+  if tmux_available; then
+    tmux_cycle_workspace_session "$session_name" "$direction" "$target_client" || {
+      json_error "Failed to cycle workspace session"
+      return 1
+    }
+    echo '{"ok":true}'
+  else
+    json_error "tmux not available"
+  fi
+}
+
+# Show Orchestra tmux shortcut help popup
+bridge_tmux_help_popup() {
+  target_client="${1:-}"
+
+  if tmux_available; then
+    tmux_show_orchestra_help_popup "$target_client" || {
+      json_error "Failed to show tmux help popup"
+      return 1
+    }
+    echo '{"ok":true}'
+  else
+    json_error "tmux not available"
+  fi
+}
+
 # Get session metadata
 bridge_session_metadata() {
   if [[ -z "${1:-}" ]]; then