feat: Add LibPDF integration for PDF form filling and signing

.agent/scripts/commands/full-loop.md

@@ -62,6 +62,27 @@ git status --short
 
 ### Step 2: Start Full Loop
 
+**Recommended: Background mode** (avoids timeout issues):
+
+```bash
+~/.aidevops/agents/scripts/full-loop-helper.sh start "$ARGUMENTS" --background
+```
+
+This starts the loop in the background and returns immediately. Use these commands to monitor:
+
+```bash
+# Check status
+~/.aidevops/agents/scripts/full-loop-helper.sh status
+
+# View logs
+~/.aidevops/agents/scripts/full-loop-helper.sh logs
+
+# Cancel if needed
+~/.aidevops/agents/scripts/full-loop-helper.sh cancel
+```
+
+**Foreground mode** (may timeout in MCP tools):
+
 ```bash
 ~/.aidevops/agents/scripts/full-loop-helper.sh start "$ARGUMENTS"
 ```
@@ -71,6 +92,8 @@ This will:
 2. Set up state tracking in `.agent/loop-state/full-loop.local.md`
 3. Begin iterating on the task
 
+**Note**: Foreground mode may timeout when called via MCP Bash tool (default 120s timeout). Use `--background` for long-running tasks.
+
 ### Step 3: Task Development (Ralph Loop)
 
 The AI will iterate on the task until outputting:
@@ -147,6 +170,7 @@ Pass options after the prompt:
 
 | Option | Description |
 |--------|-------------|
+| `--background`, `--bg` | Run in background (recommended for long tasks) |
 | `--max-task-iterations N` | Max iterations for task (default: 50) |
 | `--max-preflight-iterations N` | Max iterations for preflight (default: 5) |
 | `--max-pr-iterations N` | Max iterations for PR review (default: 20) |
@@ -158,17 +182,23 @@ Pass options after the prompt:
 ## Examples
 
 ```bash
-# Basic feature implementation
+# Basic feature implementation (background mode recommended)
+/full-loop "Add user authentication with JWT tokens" --background
+
+# Foreground mode (may timeout for long tasks)
 /full-loop "Add user authentication with JWT tokens"
 
 # Bug fix with limited iterations
-/full-loop "Fix memory leak in connection pool" --max-task-iterations 20
+/full-loop "Fix memory leak in connection pool" --max-task-iterations 20 --background
 
 # Skip postflight for quick iteration
 /full-loop "Update documentation" --skip-postflight
 
 # Manual PR creation
-/full-loop "Refactor database layer" --no-auto-pr
+/full-loop "Refactor database layer" --no-auto-pr --background
+
+# View background loop progress
+~/.aidevops/agents/scripts/full-loop-helper.sh logs
 ```
 
 ## Documentation & Changelog

.agent/scripts/full-loop-helper.sh

@@ -225,17 +225,24 @@ run_task_phase() {
     local max_iterations="${MAX_TASK_ITERATIONS:-$DEFAULT_MAX_TASK_ITERATIONS}"
 
     # Auto-detect AI tool environment if RALPH_TOOL not explicitly set
+    # Priority: RALPH_TOOL env > OPENCODE env > CLAUDE_CODE env > command availability
     local tool="${RALPH_TOOL:-}"
     if [[ -z "$tool" ]]; then
-        if [[ -n "${CLAUDE_CODE:-}" ]] || command -v claude &>/dev/null; then
+        if [[ -n "${OPENCODE:-}" ]] || [[ "${TERM_PROGRAM:-}" == "opencode" ]]; then
+            tool="opencode"
+        elif [[ -n "${CLAUDE_CODE:-}" ]]; then
             tool="claude"
         elif command -v opencode &>/dev/null; then
             tool="opencode"
+        elif command -v claude &>/dev/null; then
+            tool="claude"
         else
             tool="opencode"  # Default fallback name (will trigger legacy mode)
         fi
     fi
 
+    print_info "Detected AI tool: $tool"
+
     print_phase "Task Development" "Running Ralph loop for task implementation"
 
     # Check if ralph-loop-helper.sh exists
@@ -466,6 +473,8 @@ cmd_start() {
     local prompt="$1"
     shift
 
+    local background=false
+
     # Parse options
     while [[ $# -gt 0 ]]; do
         case "$1" in
@@ -501,6 +510,10 @@ cmd_start() {
                 DRY_RUN=true
                 shift
                 ;;
+            --background|--bg)
+                background=true
+                shift
+                ;;
             *)
                 print_error "Unknown option: $1"
                 return 1
@@ -554,12 +567,45 @@ cmd_start() {
     save_state "$PHASE_TASK" "$prompt"
     SAVED_PROMPT="$prompt"
 
-    # Start task phase
+    # Background mode: run in background with nohup
+    if [[ "$background" == "true" ]]; then
+        local log_file="${STATE_DIR}/full-loop.log"
+        local pid_file="${STATE_DIR}/full-loop.pid"
+
+        mkdir -p "$STATE_DIR"
+
+        print_info "Starting full loop in background..."
+
+        # Export variables for background process
+        export MAX_TASK_ITERATIONS MAX_PREFLIGHT_ITERATIONS MAX_PR_ITERATIONS
+        export SKIP_PREFLIGHT SKIP_POSTFLIGHT NO_AUTO_PR NO_AUTO_DEPLOY
+        export SAVED_PROMPT="$prompt"
+
+        # Start background process
+        nohup "$0" _run_foreground "$prompt" > "$log_file" 2>&1 &
+        local pid=$!
+        echo "$pid" > "$pid_file"
+
+        print_success "Full loop started in background (PID: $pid)"
+        print_info "Check status: full-loop-helper.sh status"
+        print_info "View logs: full-loop-helper.sh logs"
+        print_info "Or: tail -f $log_file"
+        return 0
+    fi
+
+    # Start task phase (foreground)
     run_task_phase "$prompt"
 
     return 0
 }
 
+# Internal command for background execution
+cmd_run_foreground() {
+    local prompt="$1"
+    run_task_phase "$prompt"
+    return 0
+}
+
 cmd_resume() {
     if ! is_loop_active; then
         print_error "No active loop to resume"
@@ -651,6 +697,20 @@ cmd_cancel() {
         return 0
     fi
 
+    # Kill background process if running
+    local pid_file="${STATE_DIR}/full-loop.pid"
+    if [[ -f "$pid_file" ]]; then
+        local pid
+        pid=$(cat "$pid_file")
+        if kill -0 "$pid" 2>/dev/null; then
+            print_info "Stopping background process (PID: $pid)..."
+            kill "$pid" 2>/dev/null || true
+            sleep 1
+            kill -9 "$pid" 2>/dev/null || true
+        fi
+        rm -f "$pid_file"
+    fi
+
     clear_state
 
     # Also cancel any sub-loops (both new and legacy locations)
@@ -663,6 +723,35 @@ cmd_cancel() {
     return 0
 }
 
+cmd_logs() {
+    local log_file="${STATE_DIR}/full-loop.log"
+    local lines="${1:-50}"
+
+    if [[ ! -f "$log_file" ]]; then
+        print_warning "No log file found. Start a loop with --background first."
+        return 1
+    fi
+
+    # Check if background process is still running
+    local pid_file="${STATE_DIR}/full-loop.pid"
+    if [[ -f "$pid_file" ]]; then
+        local pid
+        pid=$(cat "$pid_file")
+        if kill -0 "$pid" 2>/dev/null; then
+            print_info "Background process running (PID: $pid)"
+        else
+            print_warning "Background process not running (was PID: $pid)"
+        fi
+    fi
+
+    echo ""
+    echo -e "${BOLD}Full Loop Logs (last $lines lines)${NC}"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    tail -n "$lines" "$log_file"
+
+    return 0
+}
+
 cmd_complete() {
     echo ""
     echo -e "${BOLD}${GREEN}╔════════════════════════════════════════════════════════════╗${NC}"
@@ -716,6 +805,7 @@ OPTIONS:
     --no-auto-pr                  Don't auto-create PR, pause for human
     --no-auto-deploy              Don't auto-run setup.sh (aidevops only)
     --dry-run                     Show what would happen without executing
+    --background, --bg            Run in background (returns immediately)
 
 PHASES:
     1. Task Development   - Ralph loop for implementation
@@ -734,9 +824,15 @@ EXAMPLES:
     # Start full loop for a feature
     full-loop-helper.sh start "Implement user authentication with JWT"
 
+    # Start in background (recommended for long-running tasks)
+    full-loop-helper.sh start "Implement feature X" --background
+
     # Start with custom iterations
     full-loop-helper.sh start "Fix all TypeScript errors" --max-task-iterations 30
 
+    # View background loop logs
+    full-loop-helper.sh logs
+
     # Resume after manual intervention
     full-loop-helper.sh resume
 
@@ -768,6 +864,13 @@ main() {
         cancel)
             cmd_cancel
             ;;
+        logs)
+            cmd_logs "$@"
+            ;;
+        _run_foreground)
+            # Internal command for background execution
+            cmd_run_foreground "$@"
+            ;;
         help|--help|-h)
             show_help
             ;;