In `@docker/agent_cluster/agent_cluster.sh`:
- Around line 496-511: In wait_for_node, avoid embedding color variables
directly into the printf format (SC2059); change the printf calls that currently
include ${GREEN}, ${RED}, and ${RESET} in the format string to use a format
specifier like %b or %s and pass the color variables as separate arguments
(e.g., printf "%b\n" "$GREEN" "up" "$RESET"), making the calls in the success
and timeout branches use explicit format parameters instead of interpolating the
variables into the format string.
- Around line 349-353: The script currently spawns python3 five times to extract
JSON fields into variables height, bi_height, peers, mining, and syncing;
replace those with a single JSON parse invocation (either a single python3 call
or jq) that reads info_json once and emits all required values in a stable
delimiter (e.g., newline or null-separated) which you then split into the
corresponding variables (height, bi_height, peers, mining, syncing); update the
block that sets those variables to use that single parse command and ensure any
2>/dev/null handling and default fallbacks are preserved.

In `@docker/agent_cluster/docker-compose.yaml`:
- Around line 30-31: Add a proper healthcheck for the irys node and make the
peer services depend on that health state instead of just start order: add a
healthcheck stanza to the test-irys-1 service that probes the node (e.g., an
HTTP or CLI readiness check that returns success when the API is ready) and
update the peers' depends_on to use condition: service_healthy for test-irys-1
so Compose waits for readiness; verify start_peer_with_auto_restart.sh still
works with the healthcheck polling and adjust timeouts/retries in the
healthcheck to match the script's expectations.
- Around line 71-77: Update the Docker Compose network configuration under
networks -> test_network -> ipam -> config by replacing the overly broad subnet
"172.21.0.0/16" with a /24 range (e.g., "172.21.0.0/24") so the network provides
~254 usable addresses for the three-node cluster and reduces potential IP
overlap.

In `@docker/agent_cluster/start_peer_with_auto_restart.sh`:
- Around line 190-193: The parent-shell NODE_PID becomes stale because
start_node, monitor_and_restart and restart_node run in subshells; fix by using
a PID file the monitor updates and shutdown_all reads: when start_node launches
the irys process (in start_node/ restart_node) write its actual pid to a known
file (e.g., /tmp/irys-node.pid) and update that file each time restart_node
replaces the process, ensure monitor_and_restart reads/uses the same file for
tracking, and change shutdown_all to read the pid from that file (and remove it)
instead of relying on the parent-shell NODE_PID; keep NODE_PID assignment as
auxiliary but canonicalize on the pidfile so the correct, current PID is always
used for kill operations.
- Around line 85-92: The sed substitution in make_config_with_genesis using
ghash is fragile when ghash contains sed metacharacters; update
make_config_with_genesis to avoid sed delimiter/escaping issues by replacing the
sed call that edits "$TMP_CONFIG" with a robust approach (e.g., use awk with -v
hash="$ghash" and gsub to replace the exact pattern expected_genesis_hash = ""
with expected_genesis_hash = "hash", or choose a sed invocation that uses a
different delimiter and properly escapes & and \ in "$ghash"); ensure you
operate on "$TMP_CONFIG" safely (write to a temp file and move it over) and keep
TMP_CONFIG and ghash references unchanged so the function behavior stays the
same.
- Around line 94-124: The start_node function currently waits up to 30 attempts
for the genesis node to reach MIN_HEIGHT but then silently proceeds even if the
condition never met; modify the wait loop in start_node (the block using
get_height, MIN_HEIGHT, CHECK_INTERVAL_SEC and GENESIS_URL) to detect timeout
and handle it explicitly — after the for-loop, if the latest height is still <
MIN_HEIGHT, log an error including the last observed height and either exit with
a non-zero status (e.g., exit 1) or return/fail the function instead of
continuing to launch IRYS_BIN, so the peer does not start when the genesis node
is not ready.

In `@docker/Dockerfile.builder`:
- Around line 5-7: The RUN apt-get install line in the Dockerfile.builder
currently installs packages without pinned versions, making builds
non-reproducible; update the RUN command that contains "apt-get update &&
apt-get install -y --no-install-recommends build-essential pkg-config clang
cmake git ca-certificates libgmp-dev m4 file perl rsync" to either pin explicit
package versions (e.g., add =<version> for each package) or document and lock
the base distribution release (e.g., use a specific Debian/Ubuntu tag in the
FROM line) so subsequent builds install the same package versions; ensure the
change is applied to the same RUN stanza and include a short comment explaining
the chosen approach for reproducibility.

In `@docker/Dockerfile.local`:
- Around line 22-23: The two COPY lines (COPY docker/build-output/irys /app/irys
and COPY docker/entrypoint.sh /app/entrypoint.sh) assume the Docker build
context is the repository root; either update these paths to match the intended
context (e.g., if the build context is the docker/ folder use COPY
build-output/irys /app/irys and COPY entrypoint.sh /app/entrypoint.sh) or
explicitly document/ensure the build orchestration sets the context to the repo
root (add a short comment at the top of Dockerfile.local and/or update the build
script/CI step to pass the repo root as the context). Ensure the chosen approach
is consistent with the build script so the files referenced by those COPY
directives exist in the build context.
- Around line 10-30: Add a Docker HEALTHCHECK to the Dockerfile.local so
compose's depends_on can wait for the service to be ready; e.g., add a
HEALTHCHECK directive (with sensible interval/retries/timeouts) that executes a
lightweight probe against the running service (either calling the bundled binary
/app/irys with a --health/health command or invoking a small check implemented
in /app/entrypoint.sh), and if needed, extend entrypoint.sh to support a fast
exit status for the health probe; ensure the probe runs as the non-root user
(irys) or uses a helper that can run without root.

In `@docker/agent_cluster/agent_cluster.sh`:
- Around line 60-64: The logging helpers info(), ok(), warn(), and err()
currently pass color variables inside the printf format string which triggers
SC2059; change each to use a literal '%b' (or '%b\n' where a newline is needed)
as the printf format and pass the colored message as the single argument so
interpolation of ANSI sequences is done via '%b' (e.g., replace the current
printf usage in info(), ok(), warn(), err() with printf '%b\n' and build the
message using the CYAN/GREEN/YELLOW/RED, the text ($*), and RESET as the
argument).
- Around line 573-577: The current sed invocation sed -n
'/^\[consensus\.Custom\]/,$ p' captures from the [consensus.Custom] header to
EOF and can include later unrelated sections; update the extraction used before
writing to "$tmp_dir/$name" so it stops at the next TOML section header (a line
starting with '['). Replace the one-shot tailing sed with a section-aware
extractor (e.g., switch to an awk-based or sed pattern that prints from
/^\[consensus\.Custom\]/ up to but not including the next line matching /^\[/)
while preserving the subsequent filtering (grep -v '^expected_genesis_hash',
comments, and blank lines) so only the consensus.Custom block is written to
"$tmp_dir/$name".
- Line 565: The trap is defined with double quotes so $tmp_dir is expanded at
definition time; change the trap to use single quotes around the command so the
variable is expanded at execution time instead (e.g., update the trap invocation
that references tmp_dir to use single-quoted command text and keep the inner
"$tmp_dir" quoted for safety).

In @.cargo/config.toml:
- Around line 6-8: The target-specific section [target.x86_64-unknown-linux-gnu]
currently sets rustflags and overrides the global rustflags (dropping -C
target-cpu=native); update the rustflags in that section (and keep linker =
"clang") to include both flags so they are applied when building for
x86_64-unknown-linux-gnu — e.g., merge the global -C target-cpu=native into the
target's rustflags along with -C link-arg=-fuse-ld=mold so rustflags in
target.x86_64-unknown-linux-gnu contains both options.

In `@docker/agent_cluster/agent_cluster.sh`:
- Around line 485-490: cmd_status currently calls jq directly to parse info_json
into height, bi_height, peers, mining, syncing which will fail if jq is missing;
modify cmd_status to first check for jq availability (reuse the existing
have_jq() helper used in start_peer_with_auto_restart.sh) and if jq is absent,
fall back to the grep/sed extraction logic used there to populate height,
bi_height, peers, mining, and syncing, or print a clear error advising to
install jq before continuing; update the parsing branches where height,
bi_height, peers, mining, and syncing are assigned so both the jq and fallback
paths set the same variables.
- Around line 554-619: In cmd_hotdeploy, after each docker cp (both in the "all"
loop and the single-node branch), ensure the deployed binary has the expected
ownership and execute permissions by running a post-copy docker exec that sets
owner to the irys user and fixes mode (e.g., chown irys:irys /app/irys && chmod
755 /app/irys); update the "copy" phase (the loop that calls docker cp "$binary"
"${node}:/app/irys") and the single-node copy before docker restart to run this
docker exec and keep wait_for_node usage unchanged.

In `@docker/agent_cluster/docker-compose.yaml`:
- Around line 22-23: The docker compose fragment grants the NET_ADMIN capability
(cap_add: - NET_ADMIN) to containers which is overly permissive for a node
process; remove NET_ADMIN from cap_add by default and either make it opt-in via
an environment flag (e.g., ENABLE_NET_ADMIN) that conditionally adds the
capability or add an in-file comment next to the cap_add block explaining the
exact debugging tools that require NET_ADMIN and why it must be enabled; update
the docker-compose service definition where cap_add and NET_ADMIN appear to
implement the conditional enablement or the explanatory comment accordingly.

In `@docker/agent_cluster/start_peer_with_auto_restart.sh`:
- Around line 40-51: The jq pipeline in extract_height is overly complex and
fragile; replace the expression jq -r '(.height // .height? // "0") | tostring |
capture("(?<n>\\d+)")?.n // "0"' with a simpler, robust form that handles
numeric or string heights, for example jq -r '.height // 0 | tostring' (keep the
surrounding 2>/dev/null || echo "0" fallback). Update the extract_height
function to use this simpler jq expression so it returns a stable string height
for both number and string JSON values.

In `@docker/agent_cluster/agent_cluster.sh`:
- Line 534: The grep invocation in the pipeline that builds the variable matches
(matches=$(docker logs "$node" 2>&1 | grep -i "$filter" | tail -20)) treats
patterns starting with "-" as options; change the grep call to use the option
separator so it becomes grep -i -- "$filter" to force the pattern to be
interpreted as an argument, and apply the same change to the other grep instance
referenced at line 548; look for the matches variable assignment and any similar
pipelines using docker logs, node, and filter and insert the "--" after the grep
options.
- Around line 62-65: The BUILD_MEMORY calculation currently uses local_mem from
`free -g`, which truncates small machines to 0 and then falls back to an unsafe
"14g"; fix by reading memory in megabytes (use `free -m` or /proc/meminfo) into
a variable (replace `local_mem` usage with a mem_mb value), set a sensible
minimum (e.g., 512 MB) and compute BUILD_MEMORY as the larger of min_sane_value
and floor(mem_mb * 3 / 4) and append an "m" suffix; keep `CARGO_JOBS` unchanged
but ensure `BUILD_MEMORY` uses the derived mem_mb-based value instead of the 14g
hardcode so low-memory VMs/CI get a safe capped allocation.

In @.cargo/config.toml:
- Around line 6-8: The target-specific linker in .cargo/config.toml (the
[target.x86_64-unknown-linux-gnu] section) forces "clang" with
link-arg=-fuse-ld=mold but mold is not documented or installed and conflicts
with the devcontainer's ~/.cargo/config.toml which uses lld; fix by either 1)
adding mold to project docs (SETUP.md/README.md) and installing it in
.devcontainer/setup.sh, 2) moving the target.x86_64-unknown-linux-gnu linker
config out of repo-root .cargo/config.toml into a Docker-scoped or
devcontainer-only cargo config and documenting why, or 3) switching the linker
flag to a universally-available linker such as lld (make the change in
.cargo/config.toml and ensure .devcontainer/setup.sh and any user-scoped
~/.cargo/config.toml remain consistent) so local and devcontainer builds are not
broken.

In `@docker/Dockerfile.debug`:
- Line 34: The Dockerfile sets ENV RUSTFLAGS="-C target-cpu=native -C
link-arg=-fuse-ld=mold" which couples the built binary to the build host and
risks SIGILL on other machines; change the RUSTFLAGS to a portable value (e.g.,
replace target-cpu=native with target-cpu=x86-64) or add a clear comment above
the ENV line stating this image is local-only and must not be distributed, and
optionally remove or reconcile the redundant .cargo/config.toml flags brought in
by COPY . . so you don’t have duplicate/conflicting rustflags.