Why Does the Bootstrap Script Have a Hard Limit of 2 Retry Attempts?

The reverse-skill bootstrap script does not actually implement a 2-retry limit; this behavior exists only in the test suite, while the production script requires manual intervention for failures it cannot auto-resolve.

The bootstrap-reverse.sh script in the zhaoxuya520/reverse-skill repository handles the installation of reverse engineering capabilities such as jadx, apktool, and frida. Understanding why it appears to stop after two attempts requires examining both the production bootstrap logic and the test harness that validates it.

How the Bootstrap Script Actually Handles Failures

The production script processes each capability exactly once per invocation. There is no built-in retry counter or loop that limits attempts to two.

State Initialization

At the start of each capability run, the script clears three critical flags in skills/scripts/bootstrap-reverse.sh (lines 44–46):

MANUAL_REQUIRED=
LAST_CAPABILITY_MANUAL=
LAST_CAPABILITY_REGISTRATION_REQUIRED=

These flags track whether the current or previous capability requires user intervention.

Single-Pass Execution Loop

The main loop (lines 53–68) iterates through requested capabilities and calls ensure_capability for each:

for capability in "$@"; do
    ensure_capability "$capability"
    # Failure handling sets FAILED=true and optionally MANUAL_REQUIRED=true

done

If a capability fails, the script records the failure and continues (or aborts for unrecoverable errors). No automatic retry occurs.

Exit Code Determination

After processing all capabilities, the script determines the final exit status (lines 75–81):

if [ "$MANUAL_REQUIRED" = true ]; then
    exit 2  # Manual intervention required

elif [ "$FAILED" = true ]; then
    exit 1  # Generic failure

else
    exit 0  # Success

fi

Exit code 2 specifically signals that manual installation is needed—typically for commercial tools like JEB Pro that cannot be fetched automatically.

Where the "2 Retry Attempts" Originates

The perceived hard limit comes from test-bootstrap-manifest.sh (lines 65–73), which deliberately runs the bootstrap twice to validate transient failure recovery:

# First attempt – force a fetch failure

TEST_TOOLS_ROOT="$retry_root" STUB_FAIL_FETCH=1 \
    rejects_without_pnpm run_generic anything-analyzer --start-services --skip-refresh

# Second attempt – same tools dir, but with a working fetch

TEST_TOOLS_ROOT="$retry_root" STUB_PNPM_VERSION=10.24.0 \
    run_generic anything-analyzer --start-services --skip-refresh >/dev/null

This test pattern:

1. First run: Simulates a network fetch failure using STUB_FAIL_FETCH=1
2. Second run: Retries with a valid environment (STUB_PNPM_VERSION=10.24.0)
3. Verifies: No partial installation remains from the failed first run

The two-run pattern is purely a test harness construct—not a constraint in the production bootstrap logic.

Practical Examples

Normal Bootstrap Usage

Each capability is attempted once with no automatic retries:

# Install multiple tools in a single pass

bash skills/scripts/bootstrap-reverse.sh jadx apktool frida

Simulating the Test Pattern

To reproduce the test's two-attempt behavior manually:

# First run: force fetch failure

STUB_FAIL_FETCH=1 \
    bash skills/scripts/bootstrap-reverse.sh anything-analyzer --start-services --skip-refresh

# Exits 1 (FETCH_FAILED)

# Second run: retry with working environment

STUB_PNPM_VERSION=10.24.0 \
    bash skills/scripts/bootstrap-reverse.sh anything-analyzer --start-services --skip-refresh

# Exits 0 on success

Key Source Files

File	Purpose
skills/scripts/bootstrap-reverse.sh	Main bootstrapper with single-pass capability processing and exit code logic
skills/scripts/bootstrap-manifest.json	Tool definitions, URLs, and dependency metadata
skills/scripts/test-bootstrap-manifest.sh	Test harness implementing the two-run retry validation pattern

Summary

• The bootstrap script has no retry limit—it processes each capability once and exits with code 2 for manual intervention requirements
• The "2 retry attempts" pattern is test-only, located in test-bootstrap-manifest.sh (lines 65–73)
• Exit code 2 signals manual installation needed, not a retry exhaustion
• Re-invoking the script is the intended recovery mechanism for transient failures

Frequently Asked Questions

How do I retry after a bootstrap failure?

Re-run bootstrap-reverse.sh with the same arguments. The script checks existing installations and only fetches missing or outdated tools. For exit code 2 (manual required), install the indicated commercial tool manually before retrying.

What triggers exit code 2 versus exit code 1?

Exit code 2 (MANUAL_REQUIRED) occurs for capabilities like JEB Pro that require registration or purchase. Exit code 1 (FAILED) indicates technical failures such as network errors, checksum mismatches, or missing dependencies.

Can I increase the retry count in the bootstrap script?

No counter exists to modify. The script design assumes idempotent re-invocation by the user or orchestration system rather than internal retry loops. Wrap the bootstrap call in your own retry logic if needed:

for attempt in 1 2 3; do
    bash bootstrap-reverse.sh "$@" && break
    sleep 5
done

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}