run-loop.sh

#!/bin/bash

# ClosedLoop External Loop Runner
# Runs Claude iterations with fresh context by launching claude -p in a loop
# State maintained in .closedloop-ai/closedloop-loop.local.md
# Integrates with the ClosedLoop Self-Learning System

set -euo pipefail

# Claude binary path. When spawned by the closedloop-electron desktop app,
# CLAUDE_BIN is set to the absolute path that the desktop validated in its
# pre-flight check. This avoids PATH mismatches between Electron's spawn env
# and the user's login shell (e.g. non-Homebrew installs, symlinked binaries).
# Falls back to bare `claude` for manual/interactive runs where PATH is trusted.
CLAUDE="${CLAUDE_BIN:-claude}"

# Single source of truth for the state directory name
CLOSEDLOOP_STATE_DIR=".closedloop-ai"

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# State file location
STATE_FILE="$CLOSEDLOOP_STATE_DIR/closedloop-loop.local.md"
PROGRESS_LOG="$CLOSEDLOOP_STATE_DIR/closedloop-progress.log"
LOOP_USER_VISIBLE_FAILURE_FILE_NAME="loop-error.json"

# Electron provides this per-run value so the parent harness can sign intentional
# failure markers. Keep it as a shell variable, then remove the exported env var
# before spawning Claude so repository/tool commands cannot forge the marker.
LOOP_USER_VISIBLE_FAILURE_SECRET="${CLOSEDLOOP_USER_VISIBLE_FAILURE_SECRET:-}"
unset CLOSEDLOOP_USER_VISIBLE_FAILURE_SECRET

# Learning system paths
LOCK_FILE=".learnings/.lock"
SCRIPTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# Run identification
RUN_ID=""
START_SHA=""
SELF_LEARNING=false
LAST_CLAUDE_COMMAND=""
LAST_CLAUDE_SESSION_ID=""

# Write an intentionally user-visible failure marker for the Electron finalizer.
#
# This is an explicit opt-in channel only. Do not call this from ERR traps or
# generic command-failure handling; ordinary bash failures should stay generic.
# Usage:
#   fail_loop_user_visible RUNNER_ERROR XYZ "Loop execution failed because XYZ."
write_loop_user_visible_failure() {
  local code="$1"
  local subcode="$2"
  local message="$3"

  if [[ -z "${CLOSEDLOOP_WORKDIR:-}" ]]; then
    echo "Error: CLOSEDLOOP_WORKDIR is required to write loop failure marker" >&2
    return 1
  fi

  if [[ -z "$LOOP_USER_VISIBLE_FAILURE_SECRET" ]]; then
    echo "Error: CLOSEDLOOP_USER_VISIBLE_FAILURE_SECRET is required to write loop failure marker" >&2
    return 1
  fi

  case "$code" in
    RUNNER_ERROR|PRE_RUN_VALIDATION_FAILED|PLAN_STATE_UNAVAILABLE)
      ;;
    *)
      echo "Error: unsupported loop failure code: $code" >&2
      return 1
      ;;
  esac

  if [[ ! "$subcode" =~ ^[A-Z][A-Z0-9_]{2,63}$ ]]; then
    echo "Error: loop failure subcode must match ^[A-Z][A-Z0-9_]{2,63}$" >&2
    return 1
  fi

  if [[ -z "$message" || ${#message} -gt 1000 ]]; then
    echo "Error: loop failure message must be 1-1000 characters" >&2
    return 1
  fi

  local payload
  if ! payload=$(jq -n -c \
    --arg code "$code" \
    --arg message "$message" \
    --arg subcode "$subcode" \
    '{code:$code,message:$message,result:{subcode:$subcode}}'); then
    return 1
  fi

  local signature
  if ! signature=$(
    printf '%s\0%s' "$LOOP_USER_VISIBLE_FAILURE_SECRET" "$payload" \
      | python3 -c 'import hashlib, hmac, sys; secret, payload = sys.stdin.buffer.read().split(b"\0", 1); print("sha256=" + hmac.new(secret, payload, hashlib.sha256).hexdigest())'
  ); then
    return 1
  fi

  local failure_file="${CLOSEDLOOP_WORKDIR}/${LOOP_USER_VISIBLE_FAILURE_FILE_NAME}"
  local tmp_file="${failure_file}.tmp.$$"

  mkdir -p "$(dirname "$failure_file")"
  umask 077
  if ! jq -c --arg signature "$signature" '. + {signature:$signature}' \
    <<< "$payload" \
    > "$tmp_file"; then
    rm -f "$tmp_file"
    return 1
  fi
  if ! mv "$tmp_file" "$failure_file"; then
    rm -f "$tmp_file"
    return 1
  fi
}

fail_loop_user_visible() {
  local code="$1"
  local subcode="$2"
  local message="$3"

  if ! write_loop_user_visible_failure "$code" "$subcode" "$message"; then
    echo "Error: failed to write user-visible loop failure marker" >&2
  fi
  echo "CLOSEDLOOP_FATAL[$subcode]: $message" >&2
  exit 1
}

# Loop commands whose result bundle declares plan.json REQUIRED. Mirrors the
# ResultBundle manifest that the cloud side validates against (PLAN and
# REQUEST_CHANGES both require plan.json).
#
# EXECUTE is deliberately absent, and that is the load-bearing part: its
# required artifact is execution-result.json, which is only written after a
# successful commit AND push, so a legitimate no-changes EXECUTE run ends
# without it. A blanket "required artifact missing => spurious" rule would fail
# every one of those runs. Listing the non-plan commands by name below keeps
# EXECUTE excluded on purpose rather than by the accident of it not carrying a
# --prd.
LOOP_COMMANDS_OWING_PLAN="PLAN REQUEST_CHANGES"
LOOP_COMMANDS_NOT_OWING_PLAN="EXECUTE CHAT EXPLORE REQUEST_PRD_CHANGES DECOMPOSE EVALUATE_PRD GENERATE_PRD EVALUATE_PLAN EVALUATE_CODE EVALUATE_FEATURE BOOTSTRAP MANUAL"

# Normalize a command label to the canonical LoopCommand spelling.
# The desktop sets CLOSEDLOOP_COMMAND to the wire spelling (PLAN, EXECUTE,
# REQUEST_CHANGES); a local CLI run resolves it from --prompt instead, whose
# values are the prompt file names (plan-prompt, execute-prompt). Both map to
# the same command, so normalize rather than special-case the caller.
normalize_loop_command() {
  local raw="${1:-}"
  raw="${raw%-prompt}"
  raw="${raw%_prompt}"
  printf '%s' "$raw" | tr '[:lower:]-' '[:upper:]_'
}

# Does this run owe a plan.json? Echoes nothing; returns 0 (owes) or 1 (does not).
# Args: $1 = command label (raw), $2 = prd_file
#
# Version skew, both directions: an unrecognized command -- an older desktop
# sending nothing, or a newer one sending a command this script has never heard
# of -- is not an error and never blocks. It falls back to the --prd proxy,
# which is exactly the behaviour before commands were modelled at all.
run_owes_plan_json() {
  local command
  command=$(normalize_loop_command "${1:-}")
  local prd_file="${2:-}"

  case " $LOOP_COMMANDS_OWING_PLAN " in
    *" $command "*) return 0 ;;
  esac
  case " $LOOP_COMMANDS_NOT_OWING_PLAN " in
    *" $command "*) return 1 ;;
  esac

  [[ -n "$prd_file" ]]
}

# Classify the plan artifact at $1 as: missing | empty | unparseable | present.
#
# "Exists" is not "was produced". The incident evidence is literally a 0-byte
# plan.json: [[ -f ]] passes on it, jq yields nothing, and every pendingTasks
# check below reads 0 pending tasks and calls the run clean. A file that is
# absent, zero-byte, or not parseable JSON carries the same fact -- no plan was
# written -- and all three must be treated as unproduced.
classify_plan_artifact() {
  local plan_file="$1"
  if [[ ! -f "$plan_file" ]]; then
    printf 'missing'
    return
  fi
  if [[ ! -s "$plan_file" ]]; then
    printf 'empty'
    return
  fi
  if ! jq -e . "$plan_file" >/dev/null 2>&1; then
    printf 'unparseable'
    return
  fi
  printf 'present'
}

# Detect a spurious COMPLETE: the orchestrator's Phase 7 contract forbids
# emitting <promise>COMPLETE</promise> when plan.json has pending tasks, but
# it sometimes violates that contract -- typically when tasks are blocked by
# unanswered questions. Reads plan.json directly (not via validate_plan.py
# extraction) so the check still fires when the plan has format issues that
# would otherwise mask pendingTasks.
#
# Echoes a JSON object on stdout:
#   {"subcode": "...", "message": "..."}   when a violation is detected
#   {}                                      otherwise
#
# Args: $1 = workdir
#       $2 = prd file    (defaults to $PRD_FILE; tests pass it explicitly)
#       $3 = command      (defaults to $CLOSEDLOOP_COMMAND; ditto)
#
# Caller is responsible for telemetry, cleanup, and invoking
# fail_loop_user_visible.
detect_spurious_complete() {
  local workdir="$1"
  # Defaults to the global so the existing single-argument call site is
  # unchanged; passed explicitly by tests. Non-empty means this run was asked to
  # draft a plan from a PRD, which is what makes a missing plan.json a broken
  # promise rather than a run that never owed one.
  local prd_file="${2-${PRD_FILE:-}}"
  # Defaults to the global the desktop exports; passed explicitly by tests.
  local command="${3-${CLOSEDLOOP_COMMAND:-}}"
  local plan_file="$workdir/plan.json"
  local state_file="$workdir/state.json"

  # Fail OPEN when the workspace itself is gone. "The artifact was not produced"
  # and "the workspace no longer exists" are different facts, and only the first
  # one is evidence of a spurious completion. Live-exit and boot-recovery paths
  # delete the temp workdir right after finalization, so adjudicating a run
  # whose directory has already been reclaimed would flip a genuine success into
  # a failure -- a permanent divergence that no re-run can repair. A missing
  # workdir means "cannot judge", so judge nothing.
  if [[ ! -d "$workdir" ]]; then
    echo '{}'
    return
  fi

  # Skip the check when the orchestrator emitted COMPLETE as part of an
  # AWAITING_USER_SEQUENCE hard stop (e.g., the Phase 1.1 plan review
  # checkpoint). In those cases pending tasks and open questions are
  # expected -- the plan was just drafted and is waiting on the user. Only
  # a status of COMPLETED (or no state file at all) represents a final
  # completion claim that should be validated against pendingTasks.
  if [[ -f "$state_file" ]]; then
    local state_status
    state_status=$(jq -r '.status // ""' "$state_file" 2>/dev/null || echo "")
    if [[ "$state_status" == "AWAITING_USER" ]]; then
      echo '{}'
      return
    fi
  fi

  local plan_state
  plan_state=$(classify_plan_artifact "$plan_file")

  if [[ "$plan_state" != "present" ]]; then
    # A PLAN or REQUEST_CHANGES run exists to produce plan.json. Claiming
    # COMPLETE without one is the strongest spurious-completion signal there is,
    # and this branch used to wave it through: the checks below only validate
    # pendingTasks INSIDE an existing plan, so "no plan at all" -- the case that
    # actually happens -- was the one case nothing could catch.
    #
    # Observed: the orchestrator launched plan-draft-writer in the BACKGROUND,
    # said "Plan-draft-writer is running in the background. Waiting for
    # completion.", and that same turn carried the completion promise. The loop
    # ended, the writer was abandoned mid-flight, post-loop code review passed
    # vacuously over an empty diff ("the base ref you passed equals HEAD, so
    # nothing was examined"), and the run exited 0 having produced nothing. The
    # user got an implementation-plan artifact that looked done and was empty.
    #
    # Scoped per-command: a run that never owed a plan is left alone.
    #
    # REQUEST_CHANGES is included, with a known limit: the harness seeds
    # plan.json before an amend run, so PRESENCE PROVES NOTHING there. This
    # branch still catches "no plan at all" (including a seeded file truncated
    # to zero bytes), but it cannot see "the amend ran and produced nothing" --
    # that needs a pre-run baseline the detector is not given. Do not read a
    # clean result on a REQUEST_CHANGES run as proof the amend did work.
    if run_owes_plan_json "$command" "$prd_file"; then
      local plan_detail
      case "$plan_state" in
        empty)
          plan_detail="plan.json is zero bytes -- the file exists but no plan was ever written into it"
          ;;
        unparseable)
          plan_detail="plan.json is not parseable JSON -- the file exists but no usable plan was written into it"
          ;;
        *)
          plan_detail="no plan.json was ever written"
          ;;
      esac
      jq -n -c \
        --arg subcode "PLAN_MISSING_AT_COMPLETION" \
        --arg message "Loop emitted COMPLETE but $plan_detail. The planning phase did not finish -- a background plan-draft-writer that is still running when the completion promise fires is abandoned. Inspect state.json and the loop output, then re-run /code:code to continue." \
        '{subcode:$subcode,message:$message}'
      return
    fi
    echo '{}'
    return
  fi

  local pending_count
  pending_count=$(jq -r '(.pendingTasks // []) | length' "$plan_file" 2>/dev/null || echo 0)
  if ! [[ "$pending_count" =~ ^[0-9]+$ ]] || [[ "$pending_count" -eq 0 ]]; then
    echo '{}'
    return
  fi

  local pending_ids
  pending_ids=$(jq -r '(.pendingTasks // []) | map(.id // "?") | .[0:10] | join(", ")' "$plan_file" 2>/dev/null || echo "unknown")
  if [[ "$pending_count" -gt 10 ]]; then
    pending_ids="$pending_ids, +$((pending_count - 10)) more"
  fi

  local open_q_count
  open_q_count=$(jq -r '(.openQuestions // []) | length' "$plan_file" 2>/dev/null || echo 0)

  local subcode message
  if [[ "$open_q_count" =~ ^[0-9]+$ ]] && [[ "$open_q_count" -gt 0 ]]; then
    subcode="PENDING_TASKS_BLOCKED_BY_QUESTIONS"
    message="Loop emitted COMPLETE but $pending_count task(s) remain pending ($pending_ids) while $open_q_count open question(s) are unanswered in plan.json. Answer the open questions and re-run /code:code to continue."
  else
    subcode="PENDING_TASKS_AT_COMPLETION"
    message="Loop emitted COMPLETE but $pending_count task(s) still pending ($pending_ids). Inspect plan.json and re-run /code:code to continue."
  fi

  jq -n -c --arg subcode "$subcode" --arg message "$message" \
    '{subcode:$subcode,message:$message}'
}

# Handle a spurious COMPLETE: emit telemetry, release the lock, remove the
# state file, and fail out via fail_loop_user_visible (which exits 1).
# Only call when detect_spurious_complete returned a non-empty result.
handle_spurious_complete() {
  local workdir="$1"
  local iteration="$2"
  local subcode="$3"
  local message="$4"

  echo -e "\n${RED}Spurious COMPLETE detected: $message${NC}" >&2
  log_progress "Spurious COMPLETE: $message"
  write_runs_log_entry "$workdir" "$iteration" "spurious_complete" "plan_execute"
  rename_output_on_exit
  release_lock "$workdir"
  rm -f "$STATE_FILE"
  fail_loop_user_visible "RUNNER_ERROR" "$subcode" "$message"
}

# Classify Claude CLI terminal failures from one iteration's structured stream.
# The helper is side-effect free so tests can exercise new/legacy JSONL shapes
# without running the full loop.
detect_claude_terminal_failure() {
  local output_file="$1"
  local stderr_file="${2:-}"

  if [[ -s "$output_file" ]]; then
    local detection
    detection=$(jq -R -s -c '
      def entries:
        split("\n") | map(fromjson? | select(type == "object"));

      def clamp_message:
        if length > 900 then .[0:900] + "..." else . end;

      def error_string:
        if (.error? | type) == "string" then .error else "" end;

      def rate_event_message($entries):
        [
          $entries[]
          | select(.type == "rate_limit_event")
          | .rate_limit_info?
          | select(type == "object")
          | "Claude rate limit reached"
            + (if .rateLimitType then " (" + (.rateLimitType | tostring) + ")" else "" end)
            + (if .resetsAt then "; resetsAt=" + (.resetsAt | tostring) else "" end)
        ] | .[0] // "";

      def status_429:
        ((.api_error_status? | tostring) == "429")
        or ((.apiErrorStatus? | tostring) == "429");

      def envelope_text_match(pat):
        ((.is_error? == true) and ((.result? | strings | test(pat; "i")) // false))
        or ((.isApiErrorMessage? == true) and ((.error? | strings | test(pat; "i")) // false));

      def rate_limit_signal:
        ((.type? == "rate_limit_event") and (
          (.rate_limit_info? | type) == "object"
          and (
            (.rate_limit_info.status? == "rejected")
            or ((.rate_limit_info.isUsingOverage? == true) and (.rate_limit_info.overageStatus? == "rejected"))
          )
        ))
        or (error_string | ascii_downcase | test("^rate_limit(_error)?$"))
        or status_429
        or envelope_text_match("you.?ve hit your limit|usage limit|rate[_ -]?limit|rate limit reached");

      def context_limit_signal:
        envelope_text_match("prompt is too long|exceed context limit|context limit reached|conversation too long");

      def auth_challenge_signal:
        envelope_text_match("authentication_error|invalid bearer token|billing_error|permission_error|overloaded_error|api overloaded|unauthorized|token.*expired|not authenticated|please log in|login required");

      def entry_message:
        ((.result? | strings) // (.error? | strings) // "");

      def unknown_skill_signal:
        ((.result? | strings | test("Unknown skill:")) // false)
        or ((.error? | strings | test("Unknown skill:")) // false);

      entries as $entries
      | rate_event_message($entries) as $rateMessage
      | if any($entries[]; unknown_skill_signal) then
          ([$entries[] | select(unknown_skill_signal)] | .[0]) as $trigger
          | ($trigger | entry_message) as $triggerMsg
          | {
            status: "unknown_skill",
            subcode: "CLAUDE_UNKNOWN_SKILL",
            message: (
              if ($triggerMsg | length) > 0 then
                "Claude plugin command unavailable: " + $triggerMsg
              else
                "Claude plugin command unavailable: Unknown skill"
              end
              | clamp_message
            )
          }
        elif any($entries[]; rate_limit_signal) then
          ([$entries[] | select(rate_limit_signal)] | .[0]) as $trigger
          | ($trigger | entry_message) as $triggerMsg
          | {
            status: "claude_rate_limit",
            subcode: "CLAUDE_RATE_LIMIT",
            message: (
              if ($triggerMsg | length) > 0 then
                "Claude rate limit reached: " + $triggerMsg
              elif ($rateMessage | length) > 0 then
                $rateMessage
              else
                "Claude rate limit reached. Wait for the limit to reset, then re-run /code:code."
              end
              | clamp_message
            )
          }
        elif any($entries[]; context_limit_signal) then
          ([$entries[] | select(context_limit_signal)] | .[0]) as $trigger
          | ($trigger | entry_message) as $triggerMsg
          | {
            status: "context_limit",
            subcode: "CLAUDE_CONTEXT_LIMIT",
            message: (
              if ($triggerMsg | length) > 0 then
                "Claude context limit reached: " + $triggerMsg
              else
                "Claude context limit reached. Start a fresh run with a smaller prompt or reduced context."
              end
              | clamp_message
            )
          }
        elif any($entries[]; auth_challenge_signal) then
          ([$entries[] | select(auth_challenge_signal)] | .[0]) as $trigger
          | ($trigger | entry_message) as $triggerMsg
          | {
            status: "claude_auth_error",
            subcode: "CLAUDE_AUTH_CHALLENGE",
            message: (
              if ($triggerMsg | length) > 0 then
                "Claude authentication or account challenge: " + $triggerMsg
              else
                "Claude authentication or account challenge detected. Re-authenticate Claude, then re-run /code:code."
              end
              | clamp_message
            )
          }
        else
          {}
        end
    ' "$output_file" 2>/dev/null || echo '{}')

    if [[ "${DEBUG:-}" == "1" ]] && [[ "$detection" != "{}" ]]; then
      echo "[detect_claude_terminal_failure] detection=$detection" >&2
    fi

    if [[ "$detection" != "{}" ]]; then
      echo "$detection"
      return
    fi
  fi

  if [[ -s "$stderr_file" ]]; then
    local stderr_text
    stderr_text=$(tr '\n' ' ' < "$stderr_file" | sed 's/[[:space:]][[:space:]]*/ /g' | cut -c 1-800)
    if grep -qiE "you.?ve hit your limit|usage limit|rate[_ -]?limit|rate limit reached" "$stderr_file"; then
      jq -n -c --arg message "Claude rate limit reached: ${stderr_text:-Wait for the limit to reset, then re-run /code:code.}" \
        '{status:"claude_rate_limit",subcode:"CLAUDE_RATE_LIMIT",message:$message}'
      return
    fi
    if grep -qiE "prompt is too long|exceed context limit|context limit reached|conversation too long" "$stderr_file"; then
      jq -n -c --arg message "Claude context limit reached: ${stderr_text:-Start a fresh run with a smaller prompt or reduced context.}" \
        '{status:"context_limit",subcode:"CLAUDE_CONTEXT_LIMIT",message:$message}'
      return
    fi
    if grep -qiE "authentication_error|invalid bearer token|billing_error|permission_error|overloaded_error|api overloaded|unauthorized|token.*expired|not authenticated|please log in|login required" "$stderr_file"; then
      jq -n -c --arg message "Claude authentication or account challenge: ${stderr_text:-Re-authenticate Claude, then re-run /code:code.}" \
        '{status:"claude_auth_error",subcode:"CLAUDE_AUTH_CHALLENGE",message:$message}'
      return
    fi
  fi

  echo '{}'
}

# Terminal known Claude failures are intentionally user-visible: preserve the
# output sidecar for Desktop, release local state, then write the signed marker.
handle_claude_terminal_failure() {
  local workdir="$1"
  local iteration="$2"
  local status="$3"
  local subcode="$4"
  local message="$5"

  echo -e "\n${RED}Claude terminal failure detected: $message${NC}" >&2
  log_progress "Claude terminal failure [$subcode]: $message"
  write_runs_log_entry "$workdir" "$iteration" "$status" "plan_execute"
  rename_output_on_exit
  release_lock "$workdir"
  rm -f "$STATE_FILE"
  fail_loop_user_visible "RUNNER_ERROR" "$subcode" "$message"
}

# Check for jq dependency (required for learning system)
check_jq_dependency() {
  if ! command -v jq &> /dev/null; then
    echo -e "${RED}Error: jq is required for the learning system but not found${NC}"
    echo "Install with: brew install jq (macOS) or apt-get install jq (Linux)"
    exit 1
  fi
}

# Generate unique run ID
generate_run_id() {
  local timestamp=$(date +%Y%m%d-%H%M%S)
  local random_suffix=$(head -c 4 /dev/urandom | xxd -p)
  echo "${timestamp}-${random_suffix}"
}

# Acquire lock file for concurrent protection
acquire_lock() {
  local workdir="$1"
  local lock_file="$workdir/$LOCK_FILE"
  local lock_dir=$(dirname "$lock_file")

  mkdir -p "$lock_dir"

  if [[ -f "$lock_file" ]]; then
    local lock_content=$(cat "$lock_file" 2>/dev/null || echo "")
    local lock_age_seconds=0

    if [[ "$(uname)" == "Darwin" ]]; then
      lock_age_seconds=$(( $(date +%s) - $(stat -f %m "$lock_file" 2>/dev/null || echo "$(date +%s)") ))
    else
      lock_age_seconds=$(( $(date +%s) - $(stat -c %Y "$lock_file" 2>/dev/null || echo "$(date +%s)") ))
    fi

    # Consider lock stale after 4 hours
    local stale_seconds=$((4 * 3600))

    if [[ $lock_age_seconds -lt $stale_seconds ]]; then
      echo -e "${RED}Error: Another ClosedLoop loop is already running${NC}"
      echo "Lock file: $lock_file"
      echo "Lock content: $lock_content"
      echo "Lock age: $((lock_age_seconds / 60)) minutes"
      echo ""
      echo "If you're sure no other loop is running, remove the lock file:"
      echo "  rm $lock_file"
      exit 1
    else
      echo -e "${YELLOW}Warning: Found stale lock file ($((lock_age_seconds / 3600))h old), removing${NC}"
      rm -f "$lock_file"
    fi
  fi

  # Create lock file with run info
  echo "run_id=$RUN_ID|pid=$$|started=$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$lock_file"
  log_progress "Lock acquired: $lock_file"
}

# Release lock file
release_lock() {
  local workdir="$1"
  local lock_file="$workdir/$LOCK_FILE"

  if [[ -f "$lock_file" ]]; then
    rm -f "$lock_file"
    log_progress "Lock released: $lock_file"
  fi
}

# Bootstrap run-specific learnings directories
bootstrap_learnings() {
  local workdir="$1"

  if [[ "${SELF_LEARNING:-false}" != "true" ]]; then
    return
  fi

  local bootstrap_script="$SCRIPTS_DIR/bootstrap-learnings.sh"

  if [[ ! -d "$workdir/.learnings" ]]; then
    echo -e "${BLUE}Initializing learning system...${NC}"

    # Use bootstrap script to create directory structure
    if [[ -x "$bootstrap_script" ]]; then
      "$bootstrap_script" "$workdir/.learnings"
    else
      # Minimal bootstrap if script not available
      mkdir -p "$workdir/.learnings/pending"
      mkdir -p "$workdir/.learnings/sessions"
      echo -e "${GREEN}Created minimal .learnings structure${NC}"
    fi

    # Copy org learnings from .closedloop-ai/learnings/ if available (overwrite defaults)
    local org_learnings_dir=""
    local workdir_state_dir="$(dirname "$workdir")"
    # Check project root first, then the workdir-adjacent .closedloop-ai state directory.
    if [[ -d "$CLOSEDLOOP_STATE_DIR/learnings" ]]; then
      org_learnings_dir="$CLOSEDLOOP_STATE_DIR/learnings"
    elif [[ "$(basename "$workdir_state_dir")" == "$CLOSEDLOOP_STATE_DIR" ]] && [[ -d "$workdir_state_dir/learnings" ]]; then
      org_learnings_dir="$workdir_state_dir/learnings"
    fi

    if [[ -n "$org_learnings_dir" ]]; then
      echo -e "${BLUE}Copying org learnings from $org_learnings_dir${NC}"
      [[ -f "$org_learnings_dir/org-patterns.toon" ]] && cp "$org_learnings_dir/org-patterns.toon" "$workdir/.learnings/"
      [[ -f "$org_learnings_dir/goal.yaml" ]] && cp "$org_learnings_dir/goal.yaml" "$workdir/.learnings/"
      [[ -f "$org_learnings_dir/retention.yaml" ]] && cp "$org_learnings_dir/retention.yaml" "$workdir/.learnings/"
    fi
  fi
}

# Load goal configuration
load_goal_config() {
  local workdir="$1"
  local goal_file="$workdir/.learnings/goal.yaml"

  if [[ -f "$goal_file" ]] && command -v python3 &> /dev/null; then
    # Extract active goal using Python
    local active_goal=$(python3 -c "
import yaml
try:
    with open('$goal_file') as f:
        config = yaml.safe_load(f) or {}
    print(config.get('active_goal', ''))
except:
    pass
" 2>/dev/null)

    if [[ -n "$active_goal" ]]; then
      export CLOSEDLOOP_ACTIVE_GOAL="$active_goal"
      echo -e "Active goal: ${GREEN}$active_goal${NC}"
    fi
  fi
}

# Capture git SHA at start for citation verification
capture_start_sha() {
  local workdir="$1"

  if [[ -d "$workdir/.git" ]] || git -C "$workdir" rev-parse --git-dir &> /dev/null 2>&1; then
    START_SHA=$(git -C "$workdir" rev-parse HEAD 2>/dev/null || echo "")
    if [[ -n "$START_SHA" ]]; then
      log_progress "Start SHA: $START_SHA"
    fi
  fi
}

# Create iteration marker file
create_iteration_marker() {
  local workdir="$1"
  local iteration="$2"
  local session_dir="$workdir/.learnings/sessions/run-$RUN_ID"

  mkdir -p "$session_dir"
  echo "$iteration" > "$session_dir/current-iteration"
}

sanitize_runs_log_field() {
  local raw="$1"
  raw="${raw//$'\r'/ }"
  raw="${raw//$'\n'/ }"
  raw="${raw//|/_}"
  echo "$raw"
}

extract_claude_session_id() {
  local output_file="$1"
  if [[ ! -s "$output_file" ]]; then
    return 0
  fi

  jq -r '
    [
      .session_id?,
      .sessionId?,
      .message.session_id?,
      .message.sessionId?,
      .item.session_id?,
      .item.sessionId?
    ]
    | map(select(type == "string" and length > 0))
    | .[0] // empty
    | select(length > 0)
  ' "$output_file" 2>/dev/null | tail -n 1
}

record_claude_session_id() {
  local workdir="$1"
  local command="$2"
  local session_id="$3"

  if [[ -z "$session_id" ]]; then
    return 0
  fi

  LAST_CLAUDE_COMMAND="$command"
  LAST_CLAUDE_SESSION_ID="$session_id"
  export CLOSEDLOOP_SESSION_ID="$session_id"

  # Desktop finalization reads one session-id.txt. Keep that file scoped to the
  # primary plan/execute Claude session so post-loop review/fix sessions do not
  # overwrite the operation-level correlation id.
  if [[ "$command" == "plan_execute" ]]; then
    printf '%s\n' "$session_id" > "$workdir/session-id.txt"
  fi
}

# Write runs.log entry for goal evaluation and session correlation.
#
# Format:
#   run_id|timestamp|goal|iteration|status|command|last_session_id[|successful_iterations]
# The first five fields are the legacy contract; append-only fields keep older
# self-learning readers compatible while allowing command-scoped session lookup.
# The optional 8th field (successful_iterations) is appended only when provided.
write_runs_log_entry() {
  local workdir="$1"
  local iteration="$2"
  local status="${3:-in_progress}"
  local command
  local session_id
  local explicit_session_id=false
  if [[ $# -ge 4 ]]; then
    command="$4"
  else
    # Default precedence: LAST_CLAUDE_COMMAND (set after the first claude
    # invocation, accurate for review/fix sub-steps) → CLOSEDLOOP_COMMAND
    # (set by main() from parent-process pre-set or --prompt) → plan_execute.
    # `self_learning` is no longer used as a default — it overcounted on
    # fresh-start Loops before any review step had run (FEA-936 fix 1).
    command="${LAST_CLAUDE_COMMAND:-${CLOSEDLOOP_COMMAND:-plan_execute}}"
  fi
  if [[ $# -ge 5 ]]; then
    session_id="$5"
    explicit_session_id=true
  else
    session_id="${LAST_CLAUDE_SESSION_ID:-}"
  fi
  local success_count=""
  if [[ $# -ge 6 ]]; then
    success_count="$6"
  fi
  local runs_log="$workdir/runs.log"
  local timestamp
  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

  if [[ "$explicit_session_id" == "false" && -z "$session_id" && -f "$workdir/session-id.txt" ]]; then
    session_id=$(tr -d '\r\n' < "$workdir/session-id.txt" 2>/dev/null || true)
  fi

  command=$(sanitize_runs_log_field "$command")
  session_id=$(sanitize_runs_log_field "$session_id")
  mkdir -p "$(dirname "$runs_log")"
  local entry="$RUN_ID|$timestamp|${CLOSEDLOOP_ACTIVE_GOAL:-reduce-failures}|$iteration|$status|$command|$session_id"
  if [[ -n "$success_count" ]]; then
    entry="$entry|$success_count"
  fi
  echo "$entry" >> "$runs_log"
}

# Post-iteration processing: enrichment pipeline, learning capture, citation verification, success rates
post_iteration_processing() {
  local workdir="$1"
  local iteration="$2"

  log_progress "Starting post-iteration processing for iteration $iteration"

  # Export environment variables for process-learnings command
  export CLOSEDLOOP_WORKDIR="$workdir"
  export CLOSEDLOOP_RUN_ID="$RUN_ID"
  export CLOSEDLOOP_ITERATION="$iteration"

  local tools_dir="$SCRIPTS_DIR/../tools/python"
  local sl_tools_dir="$SCRIPTS_DIR/../../self-learning/tools/python"

  # Step 1: Generate changed-files.json from git diff
  if [[ -n "$START_SHA" ]]; then
    echo -e "${BLUE}[1/10] Generating changed-files.json...${NC}"
    log_progress "Step 1: Generating changed-files.json"
    mkdir -p "$workdir/.learnings"
    run_timed_step 1 "changed_files" bash -c "
      { git diff --name-only '$START_SHA' HEAD 2>/dev/null; \
        git diff --name-only HEAD 2>/dev/null; \
        git diff --name-only --cached 2>/dev/null; } \
        | sort -u \
        | python3 -c \"import json,sys; print(json.dumps([l.strip() for l in sys.stdin if l.strip()]))\" \
        > '$workdir/.learnings/changed-files.json'
    " || log_progress "Step 1: changed-files.json generation encountered errors (continuing)"
  else
    emit_skipped_step 1 "changed_files"
  fi

  if [[ "${SELF_LEARNING:-false}" == "true" ]]; then
    # Step 2: pattern_relevance.py (score patterns -> relevance-scores.json)
    local relevance_script="$sl_tools_dir/pattern_relevance.py"
    if [[ -f "$relevance_script" ]] && [[ -f "$workdir/.learnings/changed-files.json" ]]; then
      echo -e "${BLUE}[2/10] Computing pattern relevance...${NC}"
      log_progress "Step 2: Running pattern_relevance.py"
      if run_timed_step 2 "pattern_relevance" bash -c "
        python3 '$relevance_script' \
            --workdir '$workdir' \
            --changed-files '$workdir/.learnings/changed-files.json' \
            --output '$workdir/.learnings/relevance-scores.json' 2>&1 | tee -a '$PROGRESS_LOG'
      "; then
        log_progress "Step 2: Pattern relevance completed"
      else
        log_progress "Step 2: pattern_relevance.py encountered errors (continuing)"
      fi
    else
      emit_skipped_step 2 "pattern_relevance"
    fi

    # Step 3: merge_relevance.py (append relevance to outcomes.log)
    local merge_rel_script="$sl_tools_dir/merge_relevance.py"
    if [[ -f "$merge_rel_script" ]] && [[ -f "$workdir/.learnings/relevance-scores.json" ]]; then
      echo -e "${BLUE}[3/10] Merging relevance scores...${NC}"
      log_progress "Step 3: Running merge_relevance.py"
      if run_timed_step 3 "merge_relevance" bash -c "
        python3 '$merge_rel_script' \
            --workdir '$workdir' \
            --relevance-file '$workdir/.learnings/relevance-scores.json' 2>&1 | tee -a '$PROGRESS_LOG'
      "; then
        log_progress "Step 3: Relevance merge completed"
      else
        log_progress "Step 3: merge_relevance.py encountered errors (continuing)"
      fi
    else
      emit_skipped_step 3 "merge_relevance"
    fi

    # Step 4: evaluate_goal.py (evaluate goal -> goal-outcome.json)
    local eval_script="$sl_tools_dir/evaluate_goal.py"
    if [[ -f "$eval_script" ]]; then
      echo -e "${BLUE}[4/10] Evaluating goal...${NC}"
      log_progress "Step 4: Running evaluate_goal.py"
      if run_timed_step 4 "evaluate_goal" bash -c "
        python3 '$eval_script' \
            --workdir '$workdir' \
            --run-id '$RUN_ID' 2>&1 | tee -a '$PROGRESS_LOG'
      "; then
        log_progress "Step 4: Goal evaluation completed"
      else
        log_progress "Step 4: evaluate_goal.py encountered errors (continuing)"
      fi
    else
      emit_skipped_step 4 "evaluate_goal"
    fi

    # Step 5: merge_goal_outcome.py (append goal data to outcomes.log)
    local merge_goal_script="$sl_tools_dir/merge_goal_outcome.py"
    if [[ -f "$merge_goal_script" ]] && [[ -f "$workdir/.learnings/goal-outcome.json" ]]; then
      echo -e "${BLUE}[5/10] Merging goal outcome...${NC}"
      log_progress "Step 5: Running merge_goal_outcome.py"
      if run_timed_step 5 "merge_goal_outcome" bash -c "
        python3 '$merge_goal_script' \
            --workdir '$workdir' 2>&1 | tee -a '$PROGRESS_LOG'
      "; then
        log_progress "Step 5: Goal outcome merge completed"
      else
        log_progress "Step 5: merge_goal_outcome.py encountered errors (continuing)"
      fi
    else
      emit_skipped_step 5 "merge_goal_outcome"
    fi

    # Step 6: verify_citations.py (mark |unverified in outcomes.log)
    if [[ -n "$START_SHA" ]]; then
      local verify_script="$sl_tools_dir/verify_citations.py"
      if [[ -f "$verify_script" ]]; then
        echo -e "${BLUE}[6/10] Verifying citations...${NC}"
        log_progress "Step 6: Running verify_citations.py"
        if run_timed_step 6 "verify_citations" bash -c "
          python3 '$verify_script' --start-sha '$START_SHA' --workdir '$workdir' 2>&1 | tee -a '$PROGRESS_LOG'
        "; then
          log_progress "Step 6: Citation verification passed"
        else
          log_progress "Step 6: Citation verification found issues (see failures.md)"
        fi
      else
        emit_skipped_step 6 "verify_citations"
      fi
    else
      emit_skipped_step 6 "verify_citations"
    fi

    # Step 7: Merge build-validator results into outcomes.log
    local merge_build_script="$sl_tools_dir/merge_build_result.py"
    if [[ -f "$merge_build_script" ]] && [[ -f "$workdir/.learnings/build-result.json" ]]; then
      echo -e "${BLUE}[7/10] Merging build-validator results...${NC}"
      log_progress "Step 7: Running merge_build_result.py"
      if run_timed_step 7 "merge_build_result" bash -c "
        python3 '$merge_build_script' --workdir '$workdir' 2>&1 | tee -a '$PROGRESS_LOG'
      "; then
        log_progress "Step 7: Build result merge completed"
      else
        log_progress "Step 7: merge_build_result.py encountered errors (continuing)"
      fi
    else
      emit_skipped_step 7 "merge_build_result"
    fi

    # Step 8: Process pending learnings (LLM classifies and aggregates into org-patterns.toon)
    local pending_dir="$workdir/.learnings/pending"
    if [[ -d "$pending_dir" ]] && [[ -n "$(ls -A "$pending_dir"/*.json 2>/dev/null)" ]]; then
      echo -e "${BLUE}[8/10] Processing pending learnings...${NC}"
      log_progress "Step 8: Running process-learnings"
      if run_timed_step 8 "process_learnings" bash -c "
        \"$CLAUDE\" -p 'Run /self-learning:process-learnings $workdir' \
            --allowed-tools=Bash,Grep,Glob,Read,Write \
            --max-turns 100 2>&1 | tee -a '$PROGRESS_LOG'
      "; then
        log_progress "Step 8: Learning processing completed"
      else
        log_progress "Step 8: Learning processing encountered errors (continuing)"
      fi
    else
      emit_skipped_step 8 "process_learnings"
    fi

    # Step 8.5: Write merge-result.json → org-patterns.toon (deterministic)
    local merge_script="$sl_tools_dir/write_merged_patterns.py"
    local merge_result="$workdir/.learnings/merge-result.json"
    if [[ -f "$merge_result" ]] && [[ -f "$merge_script" ]]; then
      echo -e "${BLUE}[8.5/10] Writing merged patterns to TOON...${NC}"
      log_progress "Step 8.5: Running write_merged_patterns.py"
      if run_timed_step 8.5 "write_merged_patterns" bash -c "
        python3 '$merge_script' --merge-result '$merge_result' 2>&1 | tee -a '$PROGRESS_LOG'
      "; then
        log_progress "Step 8.5: TOON write completed"
        # Cleanup session files only after successful TOON write
        rm -rf "$workdir/.learnings/sessions/run-"* 2>/dev/null || true
      else
        log_progress "Step 8.5: TOON write failed — session files preserved for retry"
      fi
    else
      emit_skipped_step 8.5 "write_merged_patterns"
    fi

    # Step 9: compute_success_rates.py (deterministic rates -> update org-patterns.toon)
    local rates_script="$sl_tools_dir/compute_success_rates.py"
    if [[ -f "$rates_script" ]]; then
      echo -e "${BLUE}[9/10] Computing success rates...${NC}"
      log_progress "Step 9: Running compute_success_rates.py"
      if run_timed_step 9 "compute_success_rates" bash -c "
        python3 '$rates_script' --workdir '$workdir' 2>&1 | tee -a '$PROGRESS_LOG'
      "; then
        log_progress "Step 9: Success rate computation completed"
      else
        log_progress "Step 9: compute_success_rates.py encountered errors (continuing)"
      fi
    else
      emit_skipped_step 9 "compute_success_rates"
    fi

    # Step 10: Export closedloop learnings to global location
    if [[ -f "$workdir/.learnings/pending-closedloop.json" ]]; then
      echo -e "${BLUE}[10/10] Exporting closedloop learnings...${NC}"
      log_progress "Step 10: Running export-closedloop-learnings"
      if run_timed_step 10 "export_closedloop_learnings" bash -c "
        \"$CLAUDE\" -p '/self-learning:export-closedloop-learnings $workdir' \
            --allowed-tools=Bash,Grep,Glob,Read,Write \
            --max-turns 20 2>&1 | tee -a '$PROGRESS_LOG'
      "; then
        log_progress "Step 10: ClosedLoop learning export completed"
      else
        log_progress "Step 10: ClosedLoop learning export encountered errors (continuing)"
      fi
    else
      emit_skipped_step 10 "export_closedloop_learnings"
    fi
  else
    log_progress "Self-learning disabled, skipping post-iteration pipeline (steps 2-10)"
    emit_skipped_step 2 "pattern_relevance"
    emit_skipped_step 3 "merge_relevance"
    emit_skipped_step 4 "evaluate_goal"
    emit_skipped_step 5 "merge_goal_outcome"
    emit_skipped_step 6 "verify_citations"
    emit_skipped_step 7 "merge_build_result"
    emit_skipped_step 8 "process_learnings"
    emit_skipped_step 8.5 "write_merged_patterns"
    emit_skipped_step 9 "compute_success_rates"
    emit_skipped_step 10 "export_closedloop_learnings"
  fi
}

# Run pruning in background after loop completes
run_background_pruning() {
  local workdir="$1"

  if [[ "${SELF_LEARNING:-false}" != "true" ]]; then
    return
  fi

  local prune_script="$SCRIPTS_DIR/prune-learnings.sh"

  if [[ -x "$prune_script" ]]; then
    log_progress "Starting background pruning"
    CLOSEDLOOP_WORKDIR="$workdir" nohup "$prune_script" "$RUN_ID" >> "$PROGRESS_LOG" 2>&1 &
    echo -e "${BLUE}Background pruning started (PID: $!)${NC}"
  fi
}

# Run post-loop code review after implementation completes
run_post_loop_review() {
  local workdir="$1"

  # Skip if START_SHA is not available (no git context)
  if [[ -z "$START_SHA" ]]; then
    log_progress "Post-loop code review skipped: no START_SHA"
    return 0
  fi

  # Skip if no code changes were made (check working tree + staged + committed)
  local changed_count
  changed_count=$( {
    git diff --name-only "$START_SHA" 2>/dev/null;        # uncommitted changes vs start
    git diff --name-only --cached 2>/dev/null;             # staged changes
    git diff --name-only "$START_SHA" HEAD 2>/dev/null;    # committed changes
  } | sort -u | wc -l | tr -d ' ')
  if [[ "$changed_count" -eq 0 ]]; then
    echo -e "\n${GREEN}No code changes detected. Skipping post-loop code review.${NC}"
    log_progress "Post-loop code review skipped: no changes since $START_SHA"
    return 0
  fi

  echo -e "\n${BLUE}═══════════════════════════════════════════════════════════${NC}"
  echo -e "${BLUE}Post-Loop Code Review${NC}"
  echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}"

  log_progress "Starting post-loop code review ($changed_count files changed)"

  local formatter="$SCRIPTS_DIR/../tools/python/stream_formatter.py"
  local max_cycles="${POST_LOOP_REVIEW_CYCLES:-2}"
  local cycle=1
  local consecutive_failures=0

  while [[ "$cycle" -le "$max_cycles" ]]; do
    echo -e "\n${BLUE}Review cycle $cycle of $max_cycles${NC}"

    # --- Run review ---
    local review_start_epoch
    review_start_epoch=$(date +%s)
    local review_output
    review_output=$(mktemp)
    local review_stderr
    review_stderr=$(mktemp)
    local review_exit_file
    review_exit_file=$(mktemp)

    set +e
    (
      "$CLAUDE" \
        --allowed-tools=Bash,Grep,Glob,Read,Write,Edit,Task,TodoWrite \
        --output-format stream-json \
        --verbose \
        -p "/code-review:start --base $START_SHA" 2>"$review_stderr" \
        | { grep --line-buffered '^{' || true; } \
        | tee "$review_output" \
        | tee -a "${workdir}/claude-output.jsonl" \
        | python3 "$formatter"
      echo "${PIPESTATUS[0]}" > "$review_exit_file"
    ) &
    wait $! 2>/dev/null || true
    local review_exit
    review_exit=$(cat "$review_exit_file" 2>/dev/null || echo 1)
    rm -f "$review_exit_file"
    set -e
    local review_session_id
    review_session_id=$(extract_claude_session_id "$review_output")
    record_claude_session_id "$workdir" "code_review" "$review_session_id"

    # Guard: if the review process itself failed, don't consume stale results
    if [[ "$review_exit" -ne 0 ]]; then
      log_progress "Post-loop review failed (exit $review_exit). Skipping fix."
      write_runs_log_entry "$workdir" "${CLOSEDLOOP_ITERATION:-0}" "review_error" "code_review" "$review_session_id"
      rm -f "$review_output" "$review_stderr"
      return 0
    fi

    # Find the most recent CR_DIR (code-review session directory)
    local cr_dir
    cr_dir=$(ls -td .closedloop-ai/code-review/cr-* 2>/dev/null | head -1)

    # Read verdict from CR_DIR/verdict.json (written by code-review:start)
    local verdict="approve"
    if [[ -n "$cr_dir" ]] && [[ -f "$cr_dir/verdict.json" ]]; then
      verdict=$(jq -r '.verdict // "approve"' "$cr_dir/verdict.json" 2>/dev/null || echo "approve")
    fi

    # Emit perf event
    local review_end_epoch
    review_end_epoch=$(date +%s)
    local review_duration=$((review_end_epoch - review_start_epoch))
    emit_perf_event "$(jq -n -c \
      --arg event "post_loop_review" \
      --arg run_id "$RUN_ID" \
      --arg verdict "$verdict" \
      --argjson cycle "$cycle" \
      --argjson duration_s "$review_duration" \
      --argjson exit_code "$review_exit" \
      '{event:$event,run_id:$run_id,verdict:$verdict,cycle:$cycle,duration_s:$duration_s,exit_code:$exit_code}'
    )"
    write_runs_log_entry "$workdir" "${CLOSEDLOOP_ITERATION:-0}" "review_${verdict}" "code_review" "$review_session_id"

    rm -f "$review_output" "$review_stderr"

    if [[ "$verdict" == "approve" ]]; then
      echo -e "\n${GREEN}Code review passed${NC}"
      log_progress "Post-loop code review: approved (cycle $cycle)"
      return 0
    fi

    echo -e "\n${YELLOW}Code review found issues (verdict: $verdict). Running fix cycle...${NC}"
    log_progress "Post-loop code review: $verdict, running fix (cycle $cycle)"

    if [[ -z "$cr_dir" ]]; then
      echo -e "${RED}Warning: Could not determine code review session directory. Skipping fix.${NC}"
      log_progress "Post-loop fix skipped: CR_DIR not found"
      return 0
    fi

    # --- Run fix ---
    local fix_start_epoch
    fix_start_epoch=$(date +%s)
    local fix_output
    fix_output=$(mktemp)
    local fix_stderr
    fix_stderr=$(mktemp)
    local fix_exit_file
    fix_exit_file=$(mktemp)

    set +e
    (
      "$CLAUDE" \
        --allowed-tools=Bash,Grep,Glob,Read,Write,Edit,Task,TodoWrite \
        --output-format stream-json \
        --verbose \
        -p "/code-review:fix $cr_dir --apply" 2>"$fix_stderr" \
        | { grep --line-buffered '^{' || true; } \
        | tee "$fix_output" \
        | tee -a "${workdir}/claude-output.jsonl" \
        | python3 "$formatter"
      echo "${PIPESTATUS[0]}" > "$fix_exit_file"
    ) &
    wait $! 2>/dev/null || true
    local fix_exit
    fix_exit=$(cat "$fix_exit_file" 2>/dev/null || echo 1)
    rm -f "$fix_exit_file"
    set -e
    local fix_session_id
    fix_session_id=$(extract_claude_session_id "$fix_output")
    record_claude_session_id "$workdir" "code_review" "$fix_session_id"

    # Emit perf event for fix
    local fix_end_epoch
    fix_end_epoch=$(date +%s)
    emit_perf_event "$(jq -n -c \
      --arg event "post_loop_fix" \
      --arg run_id "$RUN_ID" \
      --argjson cycle "$cycle" \
      --argjson duration_s "$((fix_end_epoch - fix_start_epoch))" \
      --argjson exit_code "$fix_exit" \
      '{event:$event,run_id:$run_id,cycle:$cycle,duration_s:$duration_s,exit_code:$exit_code}'
    )"
    local fix_status="fix_completed"
    if [[ "$fix_exit" -ne 0 ]]; then
      fix_status="fix_error"
    fi
    write_runs_log_entry "$workdir" "${CLOSEDLOOP_ITERATION:-0}" "$fix_status" "code_review" "$fix_session_id"

    rm -f "$fix_output" "$fix_stderr"

    # Exit code contract (code-review:fix v2.13.1+):
    #   0 — made automated progress (or no findings) → continue the cycle
    #   2 — manual action required (no auto-fixes ran, manual-surface findings
    #       remain) → halt the cycle; re-running will re-detect the same findings
    #   1 (or other) — runtime error → retry per consecutive_failures policy
    if [[ "$fix_exit" -eq 2 ]]; then
      local manual_surface=0
      if [[ -f "$cr_dir/fix_result.json" ]]; then
        manual_surface=$(jq -r '.manual_surface // 0' "$cr_dir/fix_result.json" 2>/dev/null || echo 0)
      fi
      echo -e "${YELLOW}Fix surfaced $manual_surface finding(s) requiring human action — halting review cycle (no automated progress possible).${NC}"
      echo -e "${YELLOW}See $cr_dir/fix_result.json and the /code-review:fix stdout for the manual-action report.${NC}"
      log_progress "Post-loop fix cycle $cycle halted: manual action required ($manual_surface findings)"
      return 0
    fi

    if [[ "$fix_exit" -ne 0 ]]; then
      echo -e "${YELLOW}Warning: Fix subprocess failed (exit $fix_exit). Retrying on next cycle.${NC}"
      consecutive_failures=$((consecutive_failures + 1))
      if [[ "$consecutive_failures" -ge 2 ]]; then
        echo -e "${RED}Fix failed $consecutive_failures consecutive times. Skipping remaining cycles.${NC}"
        log_progress "Post-loop fix failed $consecutive_failures consecutive times. Aborting."
        return 0
      fi
    else
      consecutive_failures=0
    fi

    log_progress "Post-loop fix cycle $cycle completed (exit: $fix_exit)"
    cycle=$((cycle + 1))
  done

  log_progress "Post-loop review: max cycles ($max_cycles) reached, proceeding"
}

# Show help
show_help() {
  cat << 'EOF'
ClosedLoop Loop - External development loop with fresh context per iteration

USAGE:
  run-loop.sh <workdir> [OPTIONS]
  run-loop.sh                          # Resume existing loop from state file

ARGUMENTS:
  workdir      Path to working directory (creates new loop)

OPTIONS:
  --prd <file>                   Path to requirements/PRD file (auto-discovered if not provided)
  --prompt <name>                Orchestrator prompt name from prompts/ folder (default: prompt)
  --max-iterations <n>           Maximum iterations (default: 50)
  --completion-promise '<text>'  Promise phrase to signal completion (default: COMPLETE)
  --add-dir <path>               Add a secondary repository for multi-repo planning (repeatable)
  --self-learning                Enable self-learning (disabled by default)
  -h, --help                     Show this help message

DESCRIPTION:
  Runs Claude in a loop with fresh context on each iteration. Each iteration
  invokes `claude -p "/code:code <workdir>"`.

  State is persisted to .closedloop-ai/closedloop-loop.local.md so loops can be resumed.

  To signal completion, Claude must output: <promise>COMPLETE</promise>

LEARNING SYSTEM:
  The loop integrates with the ClosedLoop Self-Learning System:
  - Bootstraps .learnings/ directory structure on first run
  - Captures learnings from each iteration
  - Aggregates patterns into org-patterns.toon
  - Verifies citation accuracy against git diff
  - Prunes old sessions in background after completion

  Environment variables exported to each iteration:
  - CLOSEDLOOP_WORKDIR: Working directory path
  - CLOSEDLOOP_RUN_ID: Unique run identifier
  - CLOSEDLOOP_ITERATION: Current iteration number
  - CLOSEDLOOP_ACTIVE_GOAL: Active goal from goal.yaml (if set)

EXAMPLES:
  # Start a new loop
  run-loop.sh ./my-project --max-iterations 20

  # Resume an interrupted loop
  run-loop.sh

STOPPING:
  - Press Ctrl+C
  - Reach --max-iterations limit
  - Claude outputs the --completion-promise

MONITORING:
  # View current iteration:
  grep '^iteration:' .closedloop-ai/closedloop-loop.local.md

  # View progress log:
  tail -20 .closedloop-ai/closedloop-progress.log

  # View learning system status:
  ls -la .learnings/sessions/
EOF
}

# Parse arguments
WORKDIR=""
PRD_FILE=""
PROMPT_NAME=""
MAX_ITERATIONS=5
COMPLETION_PROMISE="COMPLETE"
ADD_DIRS=()

while [[ $# -gt 0 ]]; do
  case $1 in
    -h|--help)
      show_help
      exit 0
      ;;
    --add-dir)
      if [[ -z "${2:-}" ]]; then
        echo -e "${RED}Error: --add-dir requires a directory path${NC}" >&2
        exit 1
      fi
      if [[ ! -d "$2" ]]; then
        echo -e "${RED}Error: --add-dir path does not exist or is not a directory: $2${NC}" >&2
        exit 1
      fi
      ADD_DIRS+=("$2")
      shift 2
      ;;
    --prd)
      if [[ -z "${2:-}" ]]; then
        echo -e "${RED}Error: --prd requires a file path${NC}" >&2
        exit 1
      fi
      PRD_FILE="$2"
      shift 2
      ;;
    --prompt)
      if [[ -z "${2:-}" ]]; then
        echo -e "${RED}Error: --prompt requires a prompt name${NC}" >&2
        exit 1
      fi
      if [[ "$2" =~ [[:space:]] || "$2" == */* || "$2" == *..* ]]; then
        echo -e "${RED}Error: --prompt name must not contain spaces or path separators${NC}" >&2
        exit 1
      fi
      if [[ ! -f "$SCRIPTS_DIR/../prompts/$2.md" ]]; then
        echo -e "${RED}Error: prompt not found: prompts/$2.md${NC}" >&2
        exit 1
      fi
      PROMPT_NAME="$2"
      shift 2
      ;;
    --max-iterations)
      if [[ -z "${2:-}" ]] || ! [[ "$2" =~ ^[0-9]+$ ]]; then
        echo -e "${RED}Error: --max-iterations requires a positive integer${NC}" >&2
        exit 1
      fi
      MAX_ITERATIONS="$2"
      shift 2
      ;;
    --completion-promise)
      if [[ -z "${2:-}" ]]; then
        echo -e "${RED}Error: --completion-promise requires a text argument${NC}" >&2
        exit 1
      fi
      COMPLETION_PROMISE="$2"
      shift 2
      ;;
    --self-learning)
      SELF_LEARNING=true
      shift
      ;;
    -*)
      echo -e "${RED}Error: Unknown option: $1${NC}" >&2
      echo "Use --help for usage information"
      exit 1
      ;;
    *)
      if [[ -z "$WORKDIR" ]]; then
        WORKDIR="$1"
      else
        echo -e "${RED}Error: Unexpected argument: $1${NC}" >&2
        exit 1
      fi
      shift
      ;;
  esac
done

# Parse YAML frontmatter from state file
parse_frontmatter() {
  sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE"
}

get_field() {
  local field="$1"
  parse_frontmatter | grep "^${field}:" | sed "s/${field}: *//" | sed 's/^"\(.*\)"$/\1/'
}

# Extract prompt (everything after the closing ---)
get_prompt() {
  awk '/^---$/{i++; next} i>=2' "$STATE_FILE"
}

# Log to progress file
log_progress() {
  local message="$1"
  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $message" >> "$PROGRESS_LOG"
}

# --- Performance instrumentation helpers ---

# Append a single-line JSON event to perf.jsonl. The `command:` field is added
# to every event row so it can be filtered by slash command in Datadog.
emit_perf_event() {
  local json_line="$1"
  # Empty input → no-op. Two reasons: (1) historically (older jq + set -euo
  # pipefail) an empty stdin to jq propagated a non-zero exit and killed the
  # Loop; (2) even on modern jq (1.8+) which silently exits 0, the resulting
  # blank line would still get appended to perf.jsonl and corrupt downstream
  # JSONL parsers (the desktop watcher emits loop.perf.parse_failure on
  # malformed lines). Any caller that passes empty input has its own bug;
  # this guard prevents either failure mode (FEA-936 fix 2).
  if [[ -z "$json_line" ]]; then
    return 0
  fi
  local perf_file="${CLOSEDLOOP_WORKDIR:-.}/perf.jsonl"
  json_line=$(echo "$json_line" | jq -c --arg command "${CLOSEDLOOP_COMMAND:-interactive}" '. + {command:$command}')
  echo "$json_line" >> "$perf_file"
}

# Run a command with timing, emit a pipeline_step perf event, return original exit code
run_timed_step() {
  local step_num="$1"
  local step_name="$2"
  shift 2
  local step_start_epoch
  step_start_epoch=$(date +%s)
  local step_started_at
  step_started_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)

  local step_exit=0
  "$@" || step_exit=$?

  local step_end_epoch
  step_end_epoch=$(date +%s)
  local step_ended_at
  step_ended_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
  local step_duration=$((step_end_epoch - step_start_epoch))

  emit_perf_event "$(jq -n -c \
    --arg event "pipeline_step" \
    --arg run_id "$RUN_ID" \
    --argjson iteration "${CLOSEDLOOP_ITERATION:-0}" \
    --argjson step "$step_num" \
    --arg step_name "$step_name" \
    --arg started_at "$step_started_at" \
    --arg ended_at "$step_ended_at" \
    --argjson duration_s "$step_duration" \
    --argjson exit_code "$step_exit" \
    --argjson skipped false \
    '{event:$event,run_id:$run_id,iteration:$iteration,step:$step,step_name:$step_name,started_at:$started_at,ended_at:$ended_at,duration_s:$duration_s,exit_code:$exit_code,skipped:$skipped}'
  )"

  return "$step_exit"
}

# Emit a skipped pipeline_step event
emit_skipped_step() {
  local step_num="$1"
  local step_name="$2"
  local now
  now=$(date -u +%Y-%m-%dT%H:%M:%SZ)

  emit_perf_event "$(jq -n -c \
    --arg event "pipeline_step" \
    --arg run_id "$RUN_ID" \
    --argjson iteration "${CLOSEDLOOP_ITERATION:-0}" \
    --argjson step "$step_num" \
    --arg step_name "$step_name" \
    --arg started_at "$now" \
    --arg ended_at "$now" \
    --argjson duration_s 0 \
    --argjson exit_code 0 \
    --argjson skipped true \
    '{event:$event,run_id:$run_id,iteration:$iteration,step:$step,step_name:$step_name,started_at:$started_at,ended_at:$ended_at,duration_s:$duration_s,exit_code:$exit_code,skipped:$skipped}'
  )"
}

# Update iteration in state file
update_iteration() {
  local new_iter="$1"
  local temp_file="${STATE_FILE}.tmp.$$"
  sed "s/^iteration: .*/iteration: $new_iter/" "$STATE_FILE" > "$temp_file"
  mv "$temp_file" "$STATE_FILE"
}

# Update successful iteration count in state file
update_successful_iterations() {
  local new_count="$1"
  local temp_file="${STATE_FILE}.tmp.$$"
  if grep -q '^successful_iterations:' "$STATE_FILE"; then
    sed "s/^successful_iterations: .*/successful_iterations: $new_count/" "$STATE_FILE" > "$temp_file"
  else
    # Older state file predating this field — insert beneath `iteration:` so
    # resumes from in-flight legacy loops still persist subsequent counts.
    awk -v count="$new_count" '
      { print }
      /^iteration: / && !ins { print "successful_iterations: " count; ins=1 }
    ' "$STATE_FILE" > "$temp_file"
  fi
  mv "$temp_file" "$STATE_FILE"
}

# Create state file
create_state_file() {
  mkdir -p "$CLOSEDLOOP_STATE_DIR"

  # WORKDIR is the closedloop work directory passed by the caller
  # (e.g., /path/to/worktree/.closedloop-ai/work)
  mkdir -p "$WORKDIR"

  # Build the prompt - this is what gets passed to claude -p.
  # Quote values so paths with spaces survive slash-command argument parsing.
  local workdir_arg="$WORKDIR"
  workdir_arg="${workdir_arg//\\/\\\\}"
  workdir_arg="${workdir_arg//\"/\\\"}"
  workdir_arg="${workdir_arg//\$/\\\$}"
  workdir_arg="${workdir_arg//\`/\\\`}"
  local prompt="/code:code \"$workdir_arg\""
  if [[ -n "$PROMPT_NAME" ]]; then
    local prompt_name_arg="$PROMPT_NAME"
    prompt_name_arg="${prompt_name_arg//\\/\\\\}"
    prompt_name_arg="${prompt_name_arg//\"/\\\"}"
    prompt_name_arg="${prompt_name_arg//\$/\\\$}"
    prompt_name_arg="${prompt_name_arg//\`/\\\`}"
    prompt="$prompt --prompt \"$prompt_name_arg\""
  fi
  if [[ -n "$PRD_FILE" ]]; then
    local prd_arg="$PRD_FILE"
    prd_arg="${prd_arg//\\/\\\\}"
    prd_arg="${prd_arg//\"/\\\"}"
    prd_arg="${prd_arg//\$/\\\$}"
    prd_arg="${prd_arg//\`/\\\`}"
    prompt="$prompt --prd \"$prd_arg\""
  fi
  for add_dir in "${ADD_DIRS[@]+"${ADD_DIRS[@]}"}"; do
    local add_dir_arg="$add_dir"
    add_dir_arg="${add_dir_arg//\\/\\\\}"
    add_dir_arg="${add_dir_arg//\"/\\\"}"
    add_dir_arg="${add_dir_arg//\$/\\\$}"
    add_dir_arg="${add_dir_arg//\`/\\\`}"
    prompt="$prompt --add-dir \"$add_dir_arg\""
  done

  # Persist the RESOLVED command (precedence: pre-set CLOSEDLOOP_COMMAND from
  # parent process > --prompt > "interactive") rather than the raw PROMPT_NAME.
  # If we only stored PROMPT_NAME, a desktop that set CLOSEDLOOP_COMMAND but
  # never passed --prompt would write `command: ""` to state.json, and on
  # resume the restore-from-state path (line ~1507) would re-resolve to
  # "interactive" — losing the original attribution and violating PRD-254
  # §FR-1 / AC-001 across resumes.
  local resolved_command
  resolved_command=$(resolve_closedloop_command "${CLOSEDLOOP_COMMAND:-}" "$PROMPT_NAME")

  cat > "$STATE_FILE" <<EOF
---
active: true
iteration: 1
successful_iterations: 0
max_iterations: $MAX_ITERATIONS
completion_promise: "$COMPLETION_PROMISE"
workdir: "$WORKDIR"
prd_file: "$PRD_FILE"
run_id: "$RUN_ID"
start_sha: "$START_SHA"
self_learning: "$SELF_LEARNING"
command: "$resolved_command"
started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
---
$prompt
EOF

  # Update config.env with self-learning flag (preserve other keys)
  mkdir -p "$WORKDIR/$CLOSEDLOOP_STATE_DIR"
  CONFIG_FILE="$WORKDIR/$CLOSEDLOOP_STATE_DIR/config.env"
  TMP_FILE="${CONFIG_FILE}.tmp.$$"
  if [[ -f "$CONFIG_FILE" ]]; then
    sed -e '/^CLOSEDLOOP_SELF_LEARNING=/d' -e '/^CLOSEDLOOP_START_SHA=/d' "$CONFIG_FILE" > "$TMP_FILE"
  else
    : > "$TMP_FILE"
  fi
  echo "CLOSEDLOOP_SELF_LEARNING=${SELF_LEARNING:-false}" >> "$TMP_FILE"
  echo "CLOSEDLOOP_START_SHA=${START_SHA}" >> "$TMP_FILE"
  mv "$TMP_FILE" "$CONFIG_FILE"

  echo -e "${GREEN}Created new ClosedLoop loop state${NC}"
  echo -e "Working directory: ${BLUE}$WORKDIR${NC}"
  if [[ -n "$PRD_FILE" ]]; then
    echo -e "PRD file: ${BLUE}$PRD_FILE${NC}"
  fi
  echo -e "Run ID: ${BLUE}$RUN_ID${NC}"
}

# Resolve CLOSEDLOOP_COMMAND with precedence:
#   1. Pre-set value from the parent process (e.g. closedloop-electron sets
#      this from the websocket request command, before spawning run-loop.sh).
#   2. PROMPT_NAME from the --prompt CLI flag.
#   3. Literal "interactive" fallback.
#
# Lets callers tag perf events with a semantic command name (PLAN, EXECUTE, ...)
# without having to materialize a corresponding file in plugins/code/prompts/.
# Args: $1 = pre-set CLOSEDLOOP_COMMAND value (may be empty)
#       $2 = PROMPT_NAME (may be empty)
resolve_closedloop_command() {
  local preset="${1:-}"
  local prompt_name="${2:-}"
  if [[ -n "$preset" ]]; then
    echo "$preset"
  elif [[ -n "$prompt_name" ]]; then
    echo "$prompt_name"
  else
    echo "interactive"
  fi
}

# Main loop
main() {
  # Check for jq dependency
  check_jq_dependency

  # If workdir provided, create new state file
  if [[ -n "$WORKDIR" ]]; then
    # Resolve to absolute path
    WORKDIR=$(cd "$WORKDIR" 2>/dev/null && pwd || echo "$WORKDIR")

    # Generate run ID for new loop
    RUN_ID=$(generate_run_id)

    # Capture start SHA for citation verification
    capture_start_sha "$WORKDIR"

    # Bootstrap learnings directory
    bootstrap_learnings "$WORKDIR"

    # Acquire lock to prevent concurrent loops
    acquire_lock "$WORKDIR"

    rename_orphan_output_on_start

    create_state_file
  fi

  # Check for state file
  if [[ ! -f "$STATE_FILE" ]]; then
    echo -e "${RED}Error: No active ClosedLoop loop found${NC}"
    echo ""
    echo "To start a new loop:"
    echo "  run-loop.sh ./path/to/workdir"
    echo ""
    echo "For help: run-loop.sh --help"
    exit 1
  fi

  local iteration=$(get_field "iteration")
  local max_iterations=$(get_field "max_iterations")
  local completion_promise=$(get_field "completion_promise")
  local workdir=$(get_field "workdir")
  local prompt=$(get_prompt)

  # Restore RUN_ID, START_SHA, SELF_LEARNING, and PROMPT_NAME from state file if resuming
  if [[ -z "$RUN_ID" ]]; then
    RUN_ID=$(get_field "run_id")
    START_SHA=$(get_field "start_sha")
    SELF_LEARNING=$(get_field "self_learning")
    export CLOSEDLOOP_SELF_LEARNING="$SELF_LEARNING"

    # Restore PROMPT_NAME so CLOSEDLOOP_COMMAND keeps the original launching
    # command on resume (instead of degrading to "interactive" because the
    # --prompt CLI flag isn't re-passed). Older state files without `command`
    # leave PROMPT_NAME empty, preserving prior behavior.
    #
    # On a successful read of the persisted command, also override any
    # ambient CLOSEDLOOP_COMMAND in the resume shell. The persisted value is
    # authoritative for "what this Loop was launched as"; an ambient env var
    # from a different prior Loop (or a stale developer shell) shouldn't
    # rewrite history. The desktop-spawned hot path is unaffected because
    # the desktop sets CLOSEDLOOP_COMMAND to the same value that's persisted.
    if [[ -z "$PROMPT_NAME" ]]; then
      # `command` is optional on older state files predating PLN-525 / this PR.
      # Under `set -euo pipefail`, get_field's internal `grep ... | sed ...`
      # propagates a non-zero exit when the field is absent and would abort
      # run-loop.sh on resume. Match the established pattern used by the
      # cleanup/interrupt callers (see lines 1956+): tolerate missing field
      # via `|| echo ""`.
      PROMPT_NAME=$(get_field "command" 2>/dev/null || echo "")
      if [[ -n "$PROMPT_NAME" ]]; then
        CLOSEDLOOP_COMMAND="$PROMPT_NAME"
      fi
    fi

    # If resuming, re-acquire lock
    if [[ -n "$workdir" ]]; then
      acquire_lock "$workdir"
    fi
  fi

  # Effective workdir: prefer state-file value, fall back to CLI argument
  local effective_workdir="${workdir:-$WORKDIR}"

  # Validate state
  if [[ ! "$iteration" =~ ^[0-9]+$ ]]; then
    echo -e "${RED}Error: Invalid iteration in state file: $iteration${NC}"
    exit 1
  fi

  if [[ ! "$max_iterations" =~ ^[0-9]+$ ]]; then
    echo -e "${RED}Error: Invalid max_iterations in state file: $max_iterations${NC}"
    exit 1
  fi

  if [[ -z "$prompt" ]]; then
    echo -e "${RED}Error: No prompt found in state file${NC}"
    exit 1
  fi

  # Export environment variables for learning system.
  export CLOSEDLOOP_WORKDIR="$effective_workdir"
  export CLOSEDLOOP_RUN_ID="$RUN_ID"
  export CLOSEDLOOP_COMMAND="$(resolve_closedloop_command "${CLOSEDLOOP_COMMAND:-}" "$PROMPT_NAME")"

  # Load goal configuration
  load_goal_config "$effective_workdir"

  echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}"
  echo -e "${BLUE}ClosedLoop External Loop${NC}"
  echo -e "${BLUE}═══════════════════════════════════════════════════════════${NC}"
  echo ""
  echo -e "Started: ${GREEN}$(date "+%m/%d/%Y %H:%M:%S")${NC}"
  echo -e "Prompt: ${GREEN}$prompt${NC}"
  echo -e "Starting iteration: ${GREEN}$iteration${NC}"
  echo -e "Max iterations: ${YELLOW}$max_iterations${NC}"
  echo -e "Completion promise: ${YELLOW}$completion_promise${NC}"
  echo -e "Run ID: ${BLUE}$RUN_ID${NC}"
  if [[ -n "${CLOSEDLOOP_ACTIVE_GOAL:-}" ]]; then
    echo -e "Active goal: ${GREEN}${CLOSEDLOOP_ACTIVE_GOAL}${NC}"
  fi
  echo ""
  echo -e "${YELLOW}Press Ctrl+C to stop the loop at any time${NC}"
  echo ""

  log_progress "Loop started - run_id=$RUN_ID iteration=$iteration max=$max_iterations promise=$completion_promise"

  # Record run event to perf.jsonl (non-blocking).
  # Only fires on fresh-start invocations -- on resume ($WORKDIR is empty), the
  # `run` event was already appended by the original invocation, so re-emitting
  # would violate PRD-254 AC-1 ("exactly one run event per Loop").
  if [[ -n "$WORKDIR" ]]; then
    bash "$SCRIPTS_DIR/record_run.sh" "$effective_workdir" || true
  fi

  # jq filter to extract final result
  local final_result='select(.type == "result").result // empty'

  local consecutive_empty=0
  # Restore successful_iterations from state file so resumes preserve prior
  # forward progress. Legacy state files predating this field yield empty
  # output from get_field, in which case we default to 0.
  local successful_iterations
  successful_iterations=$(get_field "successful_iterations")
  if [[ ! "$successful_iterations" =~ ^[0-9]+$ ]]; then
    successful_iterations=0
  fi

  while true; do
    # Check max iterations
    if [[ $max_iterations -gt 0 ]] && [[ $iteration -gt $max_iterations ]]; then
      # Emit iteration perf event for the max-iterations boundary (no Claude run happened)
      local now_ts
      now_ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
      emit_perf_event "$(jq -n -c \
        --arg event "iteration" \
        --arg run_id "$RUN_ID" \
        --argjson iteration "$iteration" \
        --arg started_at "$now_ts" \
        --arg ended_at "$now_ts" \
        --argjson duration_s 0 \
        --argjson claude_exit_code 0 \
        --arg status "max_iterations" \
        '{event:$event,run_id:$run_id,iteration:$iteration,started_at:$started_at,ended_at:$ended_at,duration_s:$duration_s,claude_exit_code:$claude_exit_code,status:$status}'
      )"

      echo -e "\n${GREEN}Max iterations ($max_iterations) reached. Loop complete.${NC}"
      log_progress "Loop ended - max iterations reached (successful_iterations=$successful_iterations)"

      # Resolve session id at the call site so passing the success count as
      # arg 6 doesn't suppress write_runs_log_entry's normal fallback chain
      # (LAST_CLAUDE_SESSION_ID -> session-id.txt -> empty). Mirrors the
      # helper's own resolution order at lines 637 and 647-649.
      local session_id_for_log="${LAST_CLAUDE_SESSION_ID:-}"
      if [[ -z "$session_id_for_log" && -f "$effective_workdir/session-id.txt" ]]; then
        session_id_for_log=$(tr -d '\r\n' < "$effective_workdir/session-id.txt" 2>/dev/null || true)
      fi

      # Write runs.log entry (includes successful_iterations count)
      write_runs_log_entry "$effective_workdir" "$iteration" "max_iterations" "plan_execute" "$session_id_for_log" "$successful_iterations"

      # Final post-iteration processing
      post_iteration_processing "$effective_workdir" "$iteration"

      # Run post-loop code review
      run_post_loop_review "$effective_workdir"

      # Clean up
      rename_output_on_exit
      release_lock "$effective_workdir"
      rm -f "$STATE_FILE"

      # Run pruning in background
      run_background_pruning "$effective_workdir"

      if [[ $successful_iterations -eq 0 ]]; then
        write_loop_user_visible_failure "RUNNER_ERROR" "MAX_ITERATIONS_NO_PROGRESS" \
          "Iteration budget exhausted without forward progress (0/$max_iterations iterations succeeded)"
        exit 4
      fi

      exit 0
    fi

    echo -e "\n${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
    echo -e "${GREEN}Iteration $iteration${NC} (Run: $RUN_ID)"
    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"

    log_progress "Starting iteration $iteration"

    # Export iteration number for learning system
    export CLOSEDLOOP_ITERATION="$iteration"

    # Create iteration marker
    create_iteration_marker "$effective_workdir" "$iteration"

    # Capture iteration start time for perf instrumentation
    local iter_start_epoch
    iter_start_epoch=$(date +%s)
    local iter_started_at
    iter_started_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)

    # Build the full prompt - skill invocation must be the first line
    # so that claude -p recognizes and expands it properly.
    # Iteration/promise info is handled by prompt.md, not duplicated here.
    local full_prompt="$prompt"

    # Run Claude with fresh context
    local output_file=$(mktemp)
    local stderr_file=$(mktemp)

    # Run claude -p and capture output (temp file for completion check + output log)
    # Pipeline: claude -> grep JSON -> tee to output_file -> tee to jsonl log -> format for terminal
    #
    # The pipeline runs inside a background subshell so that `wait` is the
    # foreground operation.  `wait` is interruptible by trapped signals,
    # which means Ctrl+C will fire cleanup_on_interrupt immediately instead
    # of being blocked until `claude` (which catches SIGINT) exits on its own.
    local formatter="$SCRIPTS_DIR/../tools/python/stream_formatter.py"
    local exit_code_file
    exit_code_file=$(mktemp)
    set +e
    (
      "$CLAUDE" \
          --allowed-tools=Bash,Grep,Glob,Read,Edit,Write,Task,TodoWrite,Skill,WebSearch,WebFetch,mcp__playwright__browser_navigate,mcp__playwright__browser_snapshot,mcp__playwright__browser_take_screenshot,mcp__playwright__browser_click,mcp__playwright__browser_type,mcp__playwright__browser_evaluate \
          --model 'claude-opus-4-6' \
          --effort 'high' \
          --output-format stream-json \
          --verbose \
          -p "$full_prompt" 2>"$stderr_file" \
          | { grep --line-buffered '^{' || true; } \
          | tee "$output_file" \
          | tee -a "${CLOSEDLOOP_WORKDIR}/claude-output.jsonl" \
          | python3 "$formatter"
      echo "${PIPESTATUS[0]}" > "$exit_code_file"
    ) &
    wait $! 2>/dev/null || true
    local claude_exit
    claude_exit=$(cat "$exit_code_file" 2>/dev/null || echo 1)
    rm -f "$exit_code_file"
    set -e
    local plan_session_id
    plan_session_id=$(extract_claude_session_id "$output_file")
    record_claude_session_id "$effective_workdir" "plan_execute" "$plan_session_id"

    local terminal_failure
    terminal_failure=$(detect_claude_terminal_failure "$output_file" "$stderr_file")
    if [[ "$terminal_failure" != "{}" ]]; then
      local failure_status failure_subcode failure_message
      failure_status=$(echo "$terminal_failure" | jq -r '.status')
      failure_subcode=$(echo "$terminal_failure" | jq -r '.subcode')
      failure_message=$(echo "$terminal_failure" | jq -r '.message')
      rm -f "$output_file" "$stderr_file" 2>/dev/null || true
      handle_claude_terminal_failure "$effective_workdir" "$iteration" "$failure_status" "$failure_subcode" "$failure_message"
    fi

    if [[ $claude_exit -eq 0 ]]; then
      local result=$(jq -r "$final_result" "$output_file")

      # 1B: Unknown result-level errors are terminal but not user-visible
      # markers. Known Claude account/session failures are classified before
      # this branch by detect_claude_terminal_failure().
      local is_error
      is_error=$(jq -r 'select(.type == "result") | .is_error // false' "$output_file" 2>/dev/null | tail -1)
      if [[ "$is_error" == "true" ]]; then
        local error_text
        error_text=$(jq -r 'select(.type == "result") | .result // ""' "$output_file" 2>/dev/null | tail -1)
        echo -e "\n${RED}ERROR: Claude reported is_error=true in result record.${NC}"
        echo -e "${RED}Error text: $error_text${NC}"
        log_progress "Unclassified Claude result error: is_error=true, text=$error_text"
        write_runs_log_entry "$effective_workdir" "$iteration" "error" "plan_execute"
        rename_output_on_exit
        release_lock "$effective_workdir"
        rm -f "$STATE_FILE"
        rm -f "$output_file" "$stderr_file" 2>/dev/null || true
        exit 1
      fi

      # 1A: Detect consecutive empty iterations (ghost loop fix)
      if [[ -z "$result" ]]; then
        consecutive_empty=$((consecutive_empty + 1))
        if [[ $consecutive_empty -ge 3 ]]; then
          echo -e "\n${RED}ERROR: $consecutive_empty consecutive iterations with no output. Aborting to prevent ghost loop.${NC}"
          log_progress "Aborting: ghost loop detected after $consecutive_empty empty iterations"
          write_runs_log_entry "$effective_workdir" "$iteration" "ghost_loop_abort" "plan_execute"
          rename_output_on_exit
          release_lock "$effective_workdir"
          rm -f "$STATE_FILE"
          rm -f "$output_file" "$stderr_file" 2>/dev/null || true
          exit 1
        fi
      else
        consecutive_empty=0
        successful_iterations=$((successful_iterations + 1))
        update_successful_iterations "$successful_iterations"
      fi

      # Scan the full per-iteration stream for the completion promise, not
      # just the final `type==result` record. It was observed that the orchestrator may
      # emit the promise in an intermediate assistant/subagent message and then continue
      # producing output (tool_use, wrap-up text), which overwrite
      # $result and cause the completion signal to be missed. $output_file is
      # a per-iteration mktemp, so this cannot match a stale promise from a
      # prior iteration.
      local promise_found=0
      if grep -qF "<promise>$completion_promise</promise>" "$output_file"; then
        promise_found=1
      fi

      rm -f "$output_file"

      # Post-iteration processing: learning capture, aggregation, citation verification
      post_iteration_processing "$effective_workdir" "$iteration"

      # Check for completion
      if [[ $promise_found -eq 1 ]]; then
        # Count this iteration as successful if a non-empty result didn't
        # already do so (the promise found in the output stream is itself
        # evidence of forward progress).
        if [[ -z "$result" ]]; then
          successful_iterations=$((successful_iterations + 1))
          update_successful_iterations "$successful_iterations"
        fi
        # Validate that the orchestrator's COMPLETE is legitimate before
        # proceeding to post-loop code review. See detect_spurious_complete().
        local spurious_check
        spurious_check=$(detect_spurious_complete "$effective_workdir")
        local iter_status="completed"
        if [[ "$spurious_check" != "{}" ]]; then
          iter_status="spurious_complete"
        fi

        # Emit iteration perf event for the completing iteration
        local iter_end_epoch
        iter_end_epoch=$(date +%s)
        local iter_ended_at
        iter_ended_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
        local iter_duration=$((iter_end_epoch - iter_start_epoch))
        emit_perf_event "$(jq -n -c \
          --arg event "iteration" \
          --arg run_id "$RUN_ID" \
          --argjson iteration "$iteration" \
          --arg started_at "$iter_started_at" \
          --arg ended_at "$iter_ended_at" \
          --argjson duration_s "$iter_duration" \
          --argjson claude_exit_code 0 \
          --arg status "$iter_status" \
          '{event:$event,run_id:$run_id,iteration:$iteration,started_at:$started_at,ended_at:$ended_at,duration_s:$duration_s,claude_exit_code:$claude_exit_code,status:$status}'
        )"

        # Spurious COMPLETE: surface a user-visible failure marker and bail
        # out before post-loop code review (which would compound misleading
        # state). handle_spurious_complete exits 1.
        if [[ "$iter_status" == "spurious_complete" ]]; then
          local spurious_subcode spurious_message
          spurious_subcode=$(echo "$spurious_check" | jq -r '.subcode')
          spurious_message=$(echo "$spurious_check" | jq -r '.message')
          handle_spurious_complete "$effective_workdir" "$iteration" "$spurious_subcode" "$spurious_message"
        fi

        echo -e "\n${GREEN}═══════════════════════════════════════════════════════════${NC}"
        echo -e "${GREEN}Completion promise detected: $completion_promise${NC}"
        echo -e "${GREEN}Loop complete after $iteration iterations!${NC}"
        echo -e "${GREEN}═══════════════════════════════════════════════════════════${NC}"
        log_progress "Loop completed - promise fulfilled after $iteration iterations"

        # Write runs.log entry
        write_runs_log_entry "$effective_workdir" "$iteration" "completed" "plan_execute"

        # Run post-loop code review
        run_post_loop_review "$effective_workdir"

        # Clean up
        rename_output_on_exit
        release_lock "$effective_workdir"
        rm -f "$STATE_FILE"

        # Run pruning in background
        run_background_pruning "$effective_workdir"

        exit 0
      fi

      log_progress "Iteration $iteration completed - continuing"

      # Write runs.log entry
      write_runs_log_entry "$effective_workdir" "$iteration" "in_progress" "plan_execute"

    else
      echo -e "\n${YELLOW}Warning: Claude exited with non-zero status (exit code: $claude_exit)${NC}"
      if [[ -s "$stderr_file" ]]; then
        echo -e "${YELLOW}Claude stderr:${NC}"
        cat "$stderr_file"

        # 1C: Fallback for stderr-only context-limit detection. Most known
        # Claude account/session failures are classified before this branch,
        # including nonzero exits whose signal is only present in stdout JSONL.
        if grep -qiE "prompt is too long|exceed context limit|context limit reached|conversation too long" "$stderr_file"; then
          rm -f "$output_file" "$stderr_file" 2>/dev/null || true
          handle_claude_terminal_failure "$effective_workdir" "$iteration" "context_limit" "CLAUDE_CONTEXT_LIMIT" "Claude context limit reached. Start a fresh run with a smaller prompt or reduced context."
        fi
      fi
      log_progress "Iteration $iteration - Claude exited with error (code: $claude_exit)"

      # Write runs.log entry
      write_runs_log_entry "$effective_workdir" "$iteration" "error" "plan_execute"

      # Non-zero exit resets consecutive_empty -- the guard tracks consecutive
      # exit-0-with-no-output iterations, not intermixed failures.
      consecutive_empty=0

      # Still run post-iteration processing even on error
      post_iteration_processing "$effective_workdir" "$iteration"
    fi

    rm -f "$output_file" "$stderr_file" 2>/dev/null || true

    # Emit iteration perf event
    local iter_end_epoch
    iter_end_epoch=$(date +%s)
    local iter_ended_at
    iter_ended_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
    local iter_duration=$((iter_end_epoch - iter_start_epoch))
    local iter_status="ok"
    if [[ $claude_exit -ne 0 ]]; then
      iter_status="error"
    fi
    emit_perf_event "$(jq -n -c \
      --arg event "iteration" \
      --arg run_id "$RUN_ID" \
      --argjson iteration "$iteration" \
      --arg started_at "$iter_started_at" \
      --arg ended_at "$iter_ended_at" \
      --argjson duration_s "$iter_duration" \
      --argjson claude_exit_code "$claude_exit" \
      --arg status "$iter_status" \
      '{event:$event,run_id:$run_id,iteration:$iteration,started_at:$started_at,ended_at:$ended_at,duration_s:$duration_s,claude_exit_code:$claude_exit_code,status:$status}'
    )"

    # Increment iteration
    iteration=$((iteration + 1))
    update_iteration "$iteration"

    echo -e "\n${YELLOW}Continuing to iteration $iteration...${NC}"
    sleep 1  # Brief pause between iterations
  done
}

sanitize_output_run_id() {
  local raw="$1"
  raw="${raw//[^A-Za-z0-9._-]/_}"
  echo "$raw"
}

rename_orphan_output_on_start() {
  local workdir="${CLOSEDLOOP_WORKDIR:-${WORKDIR:-}}"
  if [[ -z "$workdir" ]]; then
    return
  fi

  local sidecar="${workdir}/claude-output.name.txt"
  if ! : > "$sidecar" 2>/dev/null; then
    if rm -f "$sidecar" 2>/dev/null; then
      : > "$sidecar" 2>/dev/null || \
        echo "Warning: cannot recreate empty sidecar; stale prior-run reads possible" >&2
    else
      echo "Warning: cannot clear sidecar; stale prior-run reads possible" >&2
    fi
  fi

  local jsonl_file="${workdir}/claude-output.jsonl"
  if [[ ! -f "$jsonl_file" ]]; then
    return
  fi

  local prev_run_id=""
  if [[ -f "$STATE_FILE" ]]; then
    local state_workdir
    state_workdir=$(get_field "workdir" 2>/dev/null || true)
    if [[ "$state_workdir" == "$workdir" ]]; then
      prev_run_id=$(get_field "run_id" 2>/dev/null || true)
    fi
  fi

  if [[ -z "$prev_run_id" ]]; then
    local runs_log="${workdir}/runs.log"
    if [[ -f "$runs_log" ]]; then
      local last_run_line
      last_run_line=$(tail -n 1 "$runs_log" 2>/dev/null || true)
      prev_run_id="${last_run_line%%|*}"
    fi
  fi

  if [[ -z "$prev_run_id" ]]; then
    prev_run_id="orphan-$(date +%Y%m%d-%H%M%S)"
  fi
  prev_run_id=$(sanitize_output_run_id "$prev_run_id")
  if [[ -z "$prev_run_id" ]]; then
    prev_run_id="orphan-$(date +%Y%m%d-%H%M%S)"
  fi

  local dest="${workdir}/claude-output-${prev_run_id}.jsonl"
  if ! mv "$jsonl_file" "$dest"; then
    echo "Warning: failed to rename orphaned claude-output.jsonl; truncating" >&2
    > "$jsonl_file" 2>/dev/null || \
      echo "Warning: failed to truncate claude-output.jsonl" >&2
  fi
}

rename_output_on_exit() {
  local workdir="${CLOSEDLOOP_WORKDIR:-}"
  if [[ -z "$workdir" ]]; then
    workdir=$(get_field "workdir" 2>/dev/null || echo "")
  fi
  if [[ -z "$workdir" ]]; then
    return
  fi

  local jsonl_file="${workdir}/claude-output.jsonl"
  if [[ ! -f "$jsonl_file" ]]; then
    return
  fi

  local run_id="${RUN_ID:-}"
  if [[ -z "$run_id" ]]; then
    run_id=$(get_field "run_id" 2>/dev/null || echo "")
  fi
  if [[ -z "$run_id" ]]; then
    run_id="orphan-$(date +%Y%m%d-%H%M%S)"
  fi
  run_id=$(sanitize_output_run_id "$run_id")
  if [[ -z "$run_id" ]]; then
    run_id="orphan-$(date +%Y%m%d-%H%M%S)"
  fi

  local basename="claude-output-${run_id}.jsonl"
  local dest="${workdir}/${basename}"
  if mv "$jsonl_file" "$dest"; then
    local sidecar="${workdir}/claude-output.name.txt"
    local tmp_sidecar="${sidecar}.tmp.$$"
    if printf '%s\n' "$basename" > "$tmp_sidecar" && mv "$tmp_sidecar" "$sidecar"; then
      return
    fi
    rm -f "$tmp_sidecar" "$sidecar" 2>/dev/null || true
    echo "Warning: failed to write claude-output sidecar for $basename" >&2
  else
    echo "Warning: failed to rename claude-output.jsonl to $(basename "$dest")" >&2
  fi
}

# Handle Ctrl+C gracefully
# NOTE: The pipeline is run in the background so that `wait` (which IS
# interruptible by trapped signals) is the foreground operation.  If the
# pipeline were foreground, bash would wait for it to finish before running
# the trap handler — and since `claude` catches SIGINT internally, Ctrl+C
# would appear to do nothing.
cleanup_on_interrupt() {
  echo -e "\n${YELLOW}Loop interrupted by user${NC}"
  log_progress "Loop interrupted by user at iteration $(get_field iteration 2>/dev/null || echo unknown)"

  # Kill all child processes of this script (the backgrounded pipeline)
  local pids
  pids=$(jobs -p 2>/dev/null)
  if [[ -n "$pids" ]]; then
    # shellcheck disable=SC2086 -- intentional word splitting: $pids contains newline-separated PIDs from jobs -p
    kill $pids 2>/dev/null || true
    sleep 0.5
    # shellcheck disable=SC2086
    kill -9 $pids 2>/dev/null || true
  fi

  # Release lock on interrupt
  local workdir
  workdir=$(get_field "workdir" 2>/dev/null || echo "")
  if [[ -n "$workdir" ]]; then
    rename_output_on_exit
    release_lock "$workdir"
  fi

  exit 130
}

if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
  trap cleanup_on_interrupt INT TERM
  main "$@"
fi