project-install.sh and project-update.sh scripts hang indefinitely after AgentOS 2.0 update

[olahellgren]

I could do the base install but not the project install, I only got api.md file. After extensive troubleshooting, with some help from Claude, this is what we concluded.

I have a code ready here, that I can put up in a PR: https://github.com/buildermethods/agent-os/compare/main...olahellgren:bugfix/installation-script-hangs-bash5?expand=1

Bug: Installation Scripts Hang Indefinitely with Bash 5.x

Environment

• OS: Linux (confirmed on WSL2 Ubuntu 22.04)
• Bash Version: 5.2.21
• Agent OS Version: 2.0.0
• Likely affects: Any system running Bash 5.1+ (most modern Linux distros)

Description

The installation scripts (project-install.sh and project-update.sh) hang indefinitely during execution without error messages. The script freezes after displaying the configuration, requiring manual termination (Ctrl+C or timeout).

Steps to Reproduce

1. Install Agent OS base installation:

   curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/scripts/base-install.sh | bash

2. Navigate to any project directory:

   cd /path/to/your/project

3. Run the installation script:

   ~/agent-os/scripts/project-install.sh --dry-run

4. Observed: Script hangs indefinitely after showing configuration. No error output.
5. Expected: Script should complete and show list of files to be created.

Root Cause

The set -e (exit on error) directive at line 8 of both scripts causes bash to hang when combined with complex nested subshells. Specifically:

• Command substitutions: result=$(some_function)
• Process substitutions: done < <(get_profile_files ...)
• Nested within each other across multiple function call levels

This is a documented behavior in bash 5.x where error handling in nested subshells can cause the parent shell to wait indefinitely. This affects bash 5.1+ users, which includes most modern Linux distributions.

Impact

• ❌ Cannot install Agent OS in projects (complete blocker)
• ❌ Cannot update existing installations
• ❌ Affects Ubuntu 22.04+, Fedora 35+, and other modern distros
• ❌ Affects macOS users with Homebrew bash

Solution

The fix requires changes to 3 files:

1. Remove set -e from Installation Scripts

File: scripts/project-install.sh (Line 8)
File: scripts/project-update.sh (Line 8)

# Remove this line:
set -e  # Exit on error

# Replace with this comment:
# Note: set -e is not used because it causes issues with command substitutions
# and subshells. Error handling is done explicitly throughout the script.

Rationale: The scripts already have comprehensive explicit error checking via:

• Validation functions (validate_base_installation, validate_config)
• Conditional checks before operations
• User confirmations for destructive actions

The set -e provides no additional safety but causes the hanging issue.

2. Fix Variable Scoping Issues in Common Functions

File: scripts/common-functions.sh

Three locations need to convert piped while loops to here-strings. Piped loops create subshells where variable assignments don't persist, causing bugs in exclusion checking.

Location 1: get_profile_file() function (around line 551)

# BEFORE (buggy - variable assignment lost in subshell):
local excluded=$(get_yaml_array "$profile_config" "exclude_inheritted_files" | while read pattern; do
    if match_pattern "$file_path" "$pattern"; then
        echo "yes"
        break
    fi
done)

# AFTER (correct - no subshell):
local excluded=""
local exclusions=$(get_yaml_array "$profile_config" "exclude_inheritted_files")
if [[ -n "$exclusions" ]]; then
    while read pattern; do
        if [[ -n "$pattern" ]] && match_pattern "$file_path" "$pattern"; then
            excluded="yes"
            break
        fi
    done <<< "$exclusions"
fi

Location 2: process_standards() function (around line 780)

# BEFORE:
echo "$standards_patterns" | while read pattern; do
    if [[ -z "$pattern" ]]; then
        continue
    fi
    # ... rest of processing ...
done | sort -u

# AFTER:
while read pattern; do
    if [[ -z "$pattern" ]]; then
        continue
    fi
    # ... rest of processing ...
done <<< "$standards_patterns" | sort -u

Location 3: get_profile_files() function (around line 646)

# BEFORE (nested pipes - double subshell issue):
find "$search_dir" -type f -name "*.md" -o -name "*.yml" -o -name "*.yaml" 2>/dev/null | while read file; do
    local relative_path="${file#$profile_dir/}"
    local excluded="false"
    echo "$excluded_patterns" | while read pattern; do
        if [[ -n "$pattern" ]] && match_pattern "$relative_path" "$pattern"; then
            excluded="true"
            break
        fi
    done
    # ... rest ...
done

# AFTER (here-string for inner loop):
while IFS= read -r file; do
    local relative_path="${file#$profile_dir/}"
    local excluded="false"
    while IFS= read -r pattern; do
        if [[ -n "$pattern" ]] && match_pattern "$relative_path" "$pattern"; then
            excluded="true"
            break
        fi
    done <<< "$excluded_patterns"
    # ... rest ...
done < <(find "$search_dir" -type f \( -name "*.md" -o -name "*.yml" -o -name "*.yaml" \) 2>/dev/null)

Testing Results

After applying all fixes:

Dry-run test:

$ ~/agent-os/scripts/project-install.sh --dry-run
# ✅ Completes in <2 seconds
# ✅ Shows all 23 files that would be created

Actual installation:

$ ~/agent-os/scripts/project-install.sh
# ✅ Creates agent-os/config.yml
# ✅ Creates 16 standards files
# ✅ Creates 6 Claude Code agents
# ✅ Completes successfully

No errors, warnings, or hangs observed.

Platform Testing

Confirmed working on:

• ✅ Ubuntu 22.04 (WSL2) - Bash 5.2.21

Would appreciate community testing on:

• Native Ubuntu/Debian 22.04+
• Fedora 35+
• macOS with Homebrew bash 5.x
• Other modern Linux distributions

Additional Notes

• Process substitution (done < <(...)) works fine and doesn't need changes
• The fixes are backward compatible with older bash versions
• No functionality is lost by removing set -e - error handling remains robust

Related Resources

• Bash manual on set -e: https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html
• Discussion on set -e with subshells: https://mywiki.wooledge.org/BashFAQ/105

[CasJam]

Thanks @olahellgren! This should be fixed now in 2.0.1: #177

[olahellgren]

Ok, thank you. I will test and verify.