Fix first-run blockers on Linux/macOS + clarify image upgrade procedure

README.md

@@ -99,6 +99,8 @@ $env:FUNDER_PRIVKEY = "0xYOUR_FUNDER_KEY"
 
 ### Linux / macOS (Bash)
 
+> **macOS:** Apple ships bash 3.2 (from 2007). Two of the scripts use bash 4+ syntax and will error with `bad substitution`. Install a modern bash before running the toolkit: `brew install bash && echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc`. See [docs/installation-macos.md](docs/installation-macos.md) for details.
+
 ```bash
 # One-time install (Ubuntu/Debian)
 sudo apt-get install -y docker.io

docs/installation-linux.md

@@ -10,6 +10,9 @@ Tested on **Ubuntu 24.04 LTS** with an NVIDIA RTX 4070. Should work identically
 | **NVIDIA Container Toolkit**  | latest  | Only if you want Ollama in Docker (we won't) |
 | **Ollama**                    | ≥ 0.5   | Local LLM runtime                             |
 | **Foundry (cast)**            | ≥ 1.7.1 | EVM wallet ops, contract reads                |
+| **Bash**                      | ≥ 4.0   | Required for several scripts                  |
+
+> Bash 4.0+ is required, but any mainstream distro from the last decade satisfies this (Ubuntu ≥ 10.04, RHEL ≥ 7, etc.). Run `bash --version` to confirm if unsure.
 
 ## Install steps (Ubuntu / Debian)
 

docs/installation-macos.md

@@ -24,6 +24,7 @@ If you're on an 8 GB Mac, you can run the worker but expect to lose timeouts on
 | **Docker Desktop** | ≥ 4.30  | Runs the worker container            | `brew install --cask docker`           |
 | **Ollama**         | ≥ 0.5   | Local LLM runtime                    | `brew install ollama`                  |
 | **Foundry (cast)** | ≥ 1.7.1 | EVM wallet ops, contract reads       | `curl -L https://foundry.paradigm.xyz \| bash && foundryup` |
+| **Bash**           | ≥ 4.0   | Required for several scripts         | `brew install bash`                    |
 
 ## Install steps
 
@@ -44,6 +45,12 @@ curl -L https://foundry.paradigm.xyz | bash
 ~/.foundry/bin/foundryup
 echo 'export PATH="$HOME/.foundry/bin:$PATH"' >> ~/.zshrc
 source ~/.zshrc
+
+# Modern bash (macOS ships bash 3.2; several scripts use bash 4+ syntax)
+brew install bash
+echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc   # Apple Silicon
+# On Intel Macs use: echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
 ```
 
 ## Post-install verification
@@ -54,10 +61,29 @@ docker ps                  # should return an empty table
 ollama --version
 ollama list                # may be empty
 cast --version             # cast Version: 1.7.1 or newer
+bash --version             # GNU bash, version 5.x
 ```
 
 ## macOS-specific gotchas
 
+### Apple's `/bin/bash` is version 3.2 — too old for the toolkit
+
+macOS hasn't shipped a newer bash since 2007 because bash 4+ is GPLv3 (Apple won't bundle GPLv3 code). Several scripts (e.g. `04-import-key.sh`, `06-fund-worker.sh`) use the `${var,,}` lowercase parameter expansion introduced in bash 4.0. On the stock bash you'll see:
+
+```
+./04-import-key.sh: line 35: ${reported,,}: bad substitution
+```
+
+The error fires **after** the keystore is already imported but before the address-match sanity check, leaving you in a half-done state with no clear diagnostic. Install a modern bash via Homebrew (see "Install steps" above) and make sure it's first on your `PATH`:
+
+```bash
+which bash       # should print /opt/homebrew/bin/bash (Apple Silicon)
+                 # or         /usr/local/bin/bash       (Intel)
+bash --version   # should print 5.x
+```
+
+If `which bash` still returns `/bin/bash` after install, prepend the Homebrew bin dir to `PATH` in `~/.zshrc` and open a new terminal tab.
+
 ### `host.docker.internal` works out of the box
 
 Unlike Windows, Docker Desktop for Mac sets up `host.docker.internal` resolution cleanly and uses IPv4 by default. The toolkit's default `OLLAMA_URL=http://host.docker.internal:11434` works without any tweaks.

docs/operations.md

@@ -221,21 +221,40 @@ Then re-run from Phase 01:
 
 ## Upgrading the worker image
 
-Lightchain occasionally pushes new versions of the worker image. To upgrade:
+Lightchain occasionally pushes new versions of the worker image. First, check whether there's actually a new image to pull (so you don't restart the container for no reason):
+
+```bash
+# Registry's current :latest digest (use the mainnet URL if you're on mainnet)
+curl -sSI "https://us-central1-docker.pkg.dev/v2/lightchain/lightchain-testnet-public-docker/worker/manifests/latest" \
+  -H "Accept: application/vnd.docker.distribution.manifest.list.v2+json" \
+  -H "Accept: application/vnd.oci.image.index.v1+json" \
+  -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
+  | awk 'tolower($1)=="docker-content-digest:" {print $2}' | tr -d '\r'
+
+# Your running container's image digest
+docker image inspect "$(docker inspect lightchain-worker --format '{{.Image}}')" \
+  --format '{{range .RepoDigests}}{{.}}{{"\n"}}{{end}}' | head -1
+```
+
+If the digests match, you're already current — nothing to do. If they differ, upgrade:
 
 ```powershell
+$env:NETWORK = "testnet"    # or "mainnet" — required if this is a fresh terminal
+.\scripts\powershell\01-resolve-addresses.ps1
 .\scripts\powershell\stop.ps1
 .\scripts\powershell\03-pull-image.ps1
 .\scripts\powershell\08-run-worker.ps1 -NoTail
 ```
 
 ```bash
+export NETWORK=testnet      # or mainnet — required if this is a fresh terminal
+./scripts/bash/01-resolve-addresses.sh
 ./scripts/bash/stop.sh
 ./scripts/bash/03-pull-image.sh
 ./scripts/bash/08-run-worker.sh --no-tail
 ```
 
-No re-registration needed — your on-chain state is independent of the binary version.
+No re-registration needed — your on-chain state is independent of the binary version. No other onboarding phase (00, 02, 04-07) needs to be re-run.
 
 ## Multi-worker on one machine
 

scripts/bash/env.sh

@@ -49,7 +49,13 @@ export CONTAINER_NAME="${CONTAINER_NAME:-lightchain-worker}"
 # AI_CONFIG_ADDRESS and JOB_REGISTRY_ADDRESS get populated by 01-resolve-addresses.sh
 # and persisted to scripts/bash/resolved.env. We source that file here if present.
 _SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-[[ -f "$_SCRIPT_DIR/resolved.env" ]] && source "$_SCRIPT_DIR/resolved.env"
+if [[ -f "$_SCRIPT_DIR/resolved.env" ]]; then
+  # shellcheck source=/dev/null
+  source "$_SCRIPT_DIR/resolved.env"
+fi
 
 # Secrets are loaded from scripts/bash/secrets.env (gitignored).
-[[ -f "$_SCRIPT_DIR/secrets.env" ]] && source "$_SCRIPT_DIR/secrets.env"
+if [[ -f "$_SCRIPT_DIR/secrets.env" ]]; then
+  # shellcheck source=/dev/null
+  source "$_SCRIPT_DIR/secrets.env"
+fi

scripts/powershell/env.ps1

@@ -40,7 +40,7 @@ $env:SUPPORTED_MODELS = "llama3-8b"
 # tends to lock onto the IPv6 address and the Ollama health-check ends up
 # stuck (worker_ollama_up stays at 0). Pinning to the IPv4 address that Docker
 # Desktop exposes for the Windows host fixes that.
-$env:OLLAMA_URL = "http://192.168.65.254:11434"
+$env:OLLAMA_URL = "http://host.docker.internal:11434"
 
 # Local paths. The Windows host folder is mounted into the container at /data.
 $env:KEYS_DIR = "$env:USERPROFILE\lightchain-worker\keys"