fix: add retry logic to sprint-list-epics.sh for worktree startup race condition (merge worktree-20260325-170522)

Author: JoeOakhartNava

plugins/dso/scripts/sprint-list-epics.sh

@@ -35,11 +35,26 @@ REDUCER="$SCRIPT_DIR/ticket-reducer.py"
 TRACKER_DIR="${TICKETS_TRACKER_DIR:-$REPO_ROOT/.tickets-tracker}"
 
 # ---------------------------------------------------------------------------
-# Build index from v3 reducer.
+# Retry configuration for worktree startup race conditions.
+# When the tracker dir has entries but the reducer returns an empty index,
+# retry after a short wait. This handles the case where the tracker symlink
+# or filesystem isn't fully ready yet (common during worktree creation).
+# ---------------------------------------------------------------------------
+# REVIEW-DEFENSE: MAX_RETRIES is the number of additional attempts after the initial build,
+# not the total number of attempts. Total attempts = MAX_RETRIES + 1 (initial attempt + retries).
+# The retry loop condition `attempt < MAX_RETRIES` is intentional: attempt starts at 0 and
+# increments after each retry, so the loop runs at most MAX_RETRIES times (additional attempts).
+MAX_RETRIES="${SPRINT_MAX_RETRIES:-3}"
+RETRY_WAIT="${SPRINT_RETRY_WAIT:-1}"
+
+# ---------------------------------------------------------------------------
+# Build index from v3 reducer (with retry on transient failure).
 # ---------------------------------------------------------------------------
 export _SPRINT_TRACKER_DIR="$TRACKER_DIR"
 export _SPRINT_REDUCER="$REDUCER"
-index_and_counts=$(python3 -c "
+
+_build_index() {
+python3 -c "
 import json, os, sys, importlib.util, collections
 
 tracker_dir = os.environ['_SPRINT_TRACKER_DIR']
@@ -90,7 +105,38 @@ for entry_name in os.listdir(tracker_dir):
         child_counts[parent_id] += 1
 
 print(json.dumps({'index': idx, 'child_counts': dict(child_counts)}))
-" 2>/dev/null || echo '{"index":{},"child_counts":{}}')
+" 2>/dev/null || echo '{"index":{},"child_counts":{}}'
+}
+
+# Count non-hidden subdirectories in tracker to detect "has entries but reducer failed"
+_tracker_has_entries() {
+    local count
+    count=$(find "$TRACKER_DIR" -mindepth 1 -maxdepth 1 -type d ! -name '.*' 2>/dev/null | head -1)
+    [ -n "$count" ]
+}
+
+# Build index with retry on transient failure
+index_and_counts=$(_build_index)
+
+attempt=0
+while [ "$attempt" -lt "$MAX_RETRIES" ]; do
+    # Check if the index is empty (no tickets resolved)
+    index_key_count=$(echo "$index_and_counts" | python3 -c "import json,sys; print(len(json.load(sys.stdin).get('index',{})))" 2>/dev/null || echo "0")
+
+    if [ "$index_key_count" -gt 0 ]; then
+        break  # Index has entries — proceed normally
+    fi
+
+    # Index is empty — check if tracker dir has entries (indicating transient failure)
+    if ! _tracker_has_entries; then
+        break  # Tracker genuinely has no tickets — no point retrying
+    fi
+
+    # Tracker has entries but reducer returned empty — transient failure, retry
+    attempt=$(( attempt + 1 ))
+    sleep "$RETRY_WAIT"
+    index_and_counts=$(_build_index)
+done
 
 SPRINT_INDEX_JSON=$(echo "$index_and_counts" | python3 -c "import json,sys; print(json.dumps(json.load(sys.stdin)['index']))")
 child_counts_json=$(echo "$index_and_counts" | python3 -c "import json,sys; print(json.dumps(json.load(sys.stdin)['child_counts']))")

tests/scripts/test-sprint-list-epics.sh

@@ -459,6 +459,77 @@ else
     (( FAIL++ ))
 fi
 
+# ── Test 25: Retry when tracker dir has entries but reducer returns empty ──────
+echo "Test 25: test_retry_on_transient_reducer_failure — retries when tracker not ready"
+test_retry_on_transient_reducer_failure() {
+    local TDIR25 TRACKER25
+    TDIR25=$(mktemp -d)
+    TRACKER25="$TDIR25/tracker"
+    mkdir -p "$TRACKER25"
+
+    # Create a valid v3 epic
+    make_v3_ticket "$TRACKER25" "epic-retry" "epic" "open" "1" "" "Retry Epic"
+
+    # Simulate transient reducer failure by making the epic dir temporarily unreadable.
+    # The retry mechanism should detect that the tracker has entries but the index is empty,
+    # wait, then retry — at which point the dir is readable and the epic is found.
+
+    # Make the epic dir unreadable (reducer will fail to read events, returns empty index)
+    chmod 000 "$TRACKER25/epic-retry"
+
+    # Restore permissions quickly — well before the first retry fires.
+    # SPRINT_RETRY_WAIT=0.8 gives an 8x margin over the 0.1s background delay.
+    (sleep 0.1 && chmod 755 "$TRACKER25/epic-retry") &
+    local restore_pid=$!
+
+    local out25 exit25=0
+    out25=$(TICKETS_TRACKER_DIR="$TRACKER25" SPRINT_MAX_RETRIES=3 SPRINT_RETRY_WAIT=0.8 \
+        bash "$SCRIPT" 2>/dev/null) || exit25=$?
+
+    wait "$restore_pid" 2>/dev/null || true
+    chmod -R 755 "$TRACKER25" 2>/dev/null || true
+    rm -rf "$TDIR25"
+
+    # The script should have retried and found the epic
+    [ "$exit25" -eq 0 ] || return 1
+    echo "$out25" | grep -q "epic-retry" || return 1
+}
+if test_retry_on_transient_reducer_failure; then
+    echo "  PASS: script retries on transient reducer failure"
+    (( PASS++ ))
+else
+    echo "  FAIL: script did not retry — epic-retry not found after transient failure" >&2
+    (( FAIL++ ))
+fi
+
+# ── Test 26: Retry env vars are respected (SPRINT_MAX_RETRIES=0 means no retry) ─
+echo "Test 26: test_no_retry_when_disabled — SPRINT_MAX_RETRIES=0 skips retry"
+test_no_retry_when_disabled() {
+    local TDIR26
+    TDIR26=$(mktemp -d)
+
+    # Empty tracker — no epics at all. With retry disabled, should exit 1 immediately.
+    local exit26=0 start_time end_time elapsed
+    start_time=$(python3 -c "import time; print(time.time())")
+    TICKETS_TRACKER_DIR="$TDIR26" SPRINT_MAX_RETRIES=0 SPRINT_RETRY_WAIT=2 \
+        bash "$SCRIPT" >/dev/null 2>&1 || exit26=$?
+    end_time=$(python3 -c "import time; print(time.time())")
+    elapsed=$(python3 -c "print(float('$end_time') - float('$start_time'))")
+
+    rm -rf "$TDIR26"
+
+    # Should exit 1 (no epics) and not wait 2 seconds for a retry
+    [ "$exit26" -eq 1 ] || return 1
+    python3 -c "exit(0 if float('$elapsed') < 1.5 else 1)" || return 1
+}
+if test_no_retry_when_disabled; then
+    echo "  PASS: no retry when SPRINT_MAX_RETRIES=0"
+    (( PASS++ ))
+else
+    echo "  FAIL: retry occurred even with SPRINT_MAX_RETRIES=0" >&2
+    (( FAIL++ ))
+fi
+
 echo ""
 echo "Results: $PASS passed, $FAIL failed"
 [ "$FAIL" -eq 0 ]