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

> Discover why the reverse-skill bootstrap script has a 2-retry limit in testing and what happens in production. Learn about manual intervention for unresolvable failures.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: internals
- Published: 2026-08-19

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) (lines 44–46):

```bash
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:

```bash
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):

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-bootstrap-manifest.sh) (lines 65–73), which deliberately runs the bootstrap **twice** to validate transient failure recovery:

```bash

# 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:

```bash

# 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:

```bash

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) | Main bootstrapper with single-pass capability processing and exit code logic |
| [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) | Tool definitions, URLs, and dependency metadata |
| [`skills/scripts/test-bootstrap-manifest.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

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

```