browser4-cli 4.14.0-rc.6 → 4.14.0-rc.7

package/README.md

@@ -209,7 +209,7 @@ browser4-cli fill e16 "Browser4" --submit
 # Extract data from the live page
 browser4-cli get text "h1"
 
-# Capture a static DOM snapshot for repeated extraction
+# Capture the page into the store, then extract from that copy
 browser4-cli htmlsnapshot
 browser4-cli htmlsnapshot get text "#main-content"
 browser4-cli htmlsnapshot query --sql @query.sql
@@ -235,7 +235,7 @@ These flags can appear before any command.
 | `-h`, `--help [command\|category]` | Show top-level help, category help, or detailed command help |
 | `--help-json` | Emit the machine-readable command reference |
 | `-v`, `--version` | Print the CLI version |
-| `-s`, `--session <name>` | Use a named session instead of the default session |
+| `-s`, `--session <name>` | Use a named session instead of the default session. A **global** flag: place it **before** the command (`browser4-cli -s job-42 snapshot`) — after the command it is rejected as a positional argument |
 | `--server <url>` | Override the Browser4 server URL |
 | `--timeout <seconds>` | Override the HTTP timeout for the current command |
 | `--proxy <url>` | Proxy used for runtime downloads/install operations |
@@ -257,7 +257,7 @@ These flags can appear before any command.
 | Tool | Best for | Input model | Output model |
 |---|---|---|---|
 | `snapshot` | clicking, typing, finding interactive elements | live accessibility tree | refs like `e15` |
-| `htmlsnapshot` | DOM inspection, CSS extraction, X-SQL | stored HTML snapshot | CSS selectors and query results |
+| `htmlsnapshot` | DOM inspection, CSS extraction, X-SQL | a fresh snapshot of the active page (every command captures the tab first, then reads; `--expires <dur>` reads the stored snapshot instead) | CSS selectors and query results |
 
 #### LLM configuration
 
@@ -275,6 +275,12 @@ AI-powered commands such as `extract`, `summarize`, `chat`, `agent run`, and X-S
 export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
 ```
 
+> Configure **one** provider. When several provider keys are present, the first one in the
+> built-in detection order wins — `openai` comes after the dedicated providers such as
+> `deepseek`, so a leftover `DEEPSEEK_API_KEY` silently wins over `OPENAI_*`.
+> `browser4-cli doctor` prints the key that won (`Selected key`) and the model the backend
+> will request (`Active model`). See [LLM configuration](docs/config.md#which-provider-is-used).
+
 ### Complete command reference
 
 #### Session lifecycle and server administration
@@ -289,8 +295,8 @@ export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
 | `close-all` | Close all sessions without stopping the backend. |
 | `kill-all` | Force-stop the backend and Browser4-managed browser processes. |
 | `stop` | Gracefully stop the Browser4 server. |
-| `status` | Show server version, port, health, and the web status panel URL (`http://<server>:8182/status`). When a session is active it also prints a current-session block: Name / Session ID / Status / Connection / Next open. |
-| `doctor` | Run diagnostics: build info, LLM status, stale daemon cleanup, optional repair. Supports `--verbose` and `--fix`. |
+| `status` | Show server version, port, health, and the web status panel URL (`http://<server>:18182/status`). When a session is active it also prints a current-session block: Name / Session ID / Status / Connection / Next open. |
+| `doctor` | Run diagnostics: build info, LLM status (including the configuration file it reads, the winning provider key and the active model), stale daemon cleanup, optional repair. Supports `--verbose` and `--fix`; `--fix` also writes a commented LLM config template. |
 | `doctor log [name]` | List, view, tail, or grep backend log files. Supports `--tail`, grep-style flags, and `doctor log <name> grep <pattern>`. |
 | `doctor metrics [filter]` | List, filter, or grep backend metrics. Supports `doctor metrics grep <pattern>`. |
 | `doctor status [--section <name>] [--verbose]` | Print the aggregated status panel report in the terminal: summary layer by default, full detail with `--verbose`, one report with `--section` (health, build, runtime, llm, sessions, pulsar-sessions, swarm, url-pool, browsers, drivers, privacy, plugins, skills, metrics, logs), machine-readable JSON with `--json`. |
@@ -308,7 +314,7 @@ browser4-cli doctor metrics grep request
 browser4-cli doctor status --section skills --verbose
 ```
 
-**Web status panel:** open `http://127.0.0.1:8182/status` in a browser for a live dashboard
+**Web status panel:** open `http://127.0.0.1:18182/status` in a browser for a live dashboard
 (health, version, JVM/runtime, LLM config, sessions, **Pulsar sessions** — SDK identity,
 context and main-loop state, **swarm** — swarm session plus task summary, **URL pool** —
 queued/real-time/delay counts per priority cache, browsers & open tabs — per-session
@@ -322,7 +328,7 @@ is backed by the aggregated `GET /api/system/status` endpoint; the individual en
 reports load/enable state and SDK version for every installed plugin; the same reports can be
 read from the terminal with `browser4-cli doctor status`.
 
-**Page screenshots:** open `http://127.0.0.1:8182/pages.html` for a grid of every open page
+**Page screenshots:** open `http://127.0.0.1:18182/pages.html` for a grid of every open page
 across sessions. The active tab of each session is captured automatically (click a screenshot
 to re-capture it); inactive tabs show a placeholder that captures on click. Swarm sessions only
 show placeholders. Screenshots load **asynchronously** — the backend captures in the background
@@ -358,7 +364,7 @@ All interaction commands accept a snapshot ref such as `e15` or a CSS selector u
 | `wait [target]` | Wait for a selector/ref, duration, text, URL pattern, page-load state, or JavaScript expression. Supports `--timeout`, `--text`, `--url`, `--load`, `--fn`. |
 | `upload <ref> <file> [file...]` | Upload one or more local files to a page file input. The target must be an `<input type="file">` (anything else errors); the paths must be readable by the browser process — local mode: the same machine, and empty/missing files are rejected with a hint; remote backend: paths resolve on the backend host. Supports `--no-snapshot`. |
 
-`wait --load` accepts `domcontentloaded`, `load`, and `networkidle`.
+`wait --load` accepts `domcontentloaded`, `load`, and `networkidle`. `networkidle` only proves the network went quiet — it does **not** mean late-rendered results exist; for result pages poll the element instead: `wait "<result-selector>"`.
 
 ```bash
 browser4-cli click e8 --follow
@@ -419,25 +425,27 @@ browser4-cli cdp Runtime.evaluate --json '{"expression":"document.title"}'
 
 #### HTML snapshot and X-SQL extraction
 
-`htmlsnapshot` captures a stored raw DOM snapshot and is the center of Browser4's structured extraction workflow.
+`htmlsnapshot` captures a raw DOM snapshot of the page the active tab is showing and is the center of Browser4's structured extraction workflow. **Every `htmlsnapshot` command works on a fresh snapshot of the active page**: it captures the tab first (serializing the document the tab already shows, without navigating) and then operates on that snapshot — `capture` returns the metadata, while the reads consume it, so a read already sees the live document (form results, SPA updates, `eval` mutations). A read can also be told to serve the **stored** snapshot instead: `--expires <dur>` (default `0s`, the live page) serves the stored copy of the active page while it is younger than the window — `htmlsnapshot get text ".price" --expires 1d` reads the previous snapshot version and never touches the tab. A command aimed at another URL (`readability <url>`, `query --url <url>`) reads *that URL's* stored copy, or an independent read-only load when the store has nothing — a URL the tab does not show is never captured, so the tab's document is never filed under it.
 
 | Command | Description |
 |---|---|
 | `htmlsnapshot` | Short form of `htmlsnapshot capture`. |
 | `htmlsnapshot capture` | Capture and store a static HTML snapshot with metadata about the page and interactive elements. |
-| `htmlsnapshot get <field> [selector] [name]` | Extract the first matching `text`, `html`, or `attr` from the stored snapshot. |
-| `htmlsnapshot get all <field> [selector] [name]` | Extract all matching values from the stored snapshot. Supports `--offset` and `--limit`. |
-| `htmlsnapshot query [url]` | Run X-SQL. Supports `--sql <query\|@file>`, `--sql-stdin`, `--sql-base64`, result pagination, and extraction-focused output flags. |
-| `htmlsnapshot export` | Export stored HTML to a file. Supports positional file path or `--file <path>` plus `--clean`. |
-| `htmlsnapshot summary` | Generate a compressed Web Page Summary Index (WPSI). |
-| `htmlsnapshot grep <pattern>` | Search stored HTML with grep-style flags. |
-| `htmlsnapshot inspect [selector]` | Discover recurring DOM patterns and selector candidates. Supports `--max`, `--depth`, `--stdin`, `--selector-base64`. |
-| `htmlsnapshot readability [url]` | Extract the main article content with a Readability-style heuristic — no LLM, no tokens. Supports `--text-only` and pagination. |
+| `htmlsnapshot get <field> [selector] [name]` | Extract the first matching `text`, `textcontent`, `html`, or `attr` from a fresh snapshot of the active page. Supports `--expires <dur>`. |
+| `htmlsnapshot get all <field> [selector] [name]` | Extract all matching values from a fresh snapshot of the active page. Supports `--offset`, `--limit`, and `--expires <dur>`. |
+| `htmlsnapshot query [url]` | Run X-SQL against a fresh snapshot of the active page, or against an explicit URL's stored page. Supports `--sql <query\|@file>`, `--sql-stdin`, `--sql-base64`, `--expires <dur>`, result pagination, and extraction-focused output flags. |
+| `htmlsnapshot export` | Export a fresh snapshot's HTML to a file. Supports positional file path or `--file <path>` plus `--clean` and `--expires <dur>`. |
+| `htmlsnapshot summary [--algorithm <id>]` | Generate a compressed Web Page Summary Index (WPSI) from a fresh snapshot of the active page; plugins may contribute additional algorithm ids. Supports `--expires <dur>`. |
+| `htmlsnapshot algorithms` | List installed summary algorithms (built-in `wpsi` plus plugin-contributed ids). No page required. |
+| `htmlsnapshot grep <pattern>` | Search a fresh snapshot's HTML with grep-style flags. Supports `--expires <dur>`. |
+| `htmlsnapshot inspect [selector]` | Discover recurring DOM patterns and selector candidates in a fresh snapshot of the active page. Supports `--max`, `--depth`, `--stdin`, `--selector-base64`, `--expires <dur>`. |
+| `htmlsnapshot readability [url]` | Extract the main article content with a Readability-style heuristic — no LLM, no tokens. Without a URL: the active page; with one: that URL's own stored copy. Supports `--text-only`, `--expires <dur>`, and pagination. |
 
 Important rules:
 
 - use `snapshot` when you need refs and interaction
-- use `htmlsnapshot` when you need repeated DOM extraction
+- use `htmlsnapshot` when you need repeated DOM extraction — every command captures the tab first, so simply rerunning it sees the page as it is now
+- use `--expires <dur>` on a read when you want the snapshot already in the store (`--expires 1d`) instead of the live page (`--expires 0s`, the default) — the stored copy is left untouched and the tab is not serialized
 - `htmlsnapshot query --sql @query.sql` is the recommended way to avoid shell quoting issues
 - for correlated list extraction, prefer `htmlsnapshot query` over repeated `get all`
 - for one-step article extraction (no selectors needed), use `htmlsnapshot readability`
@@ -581,15 +589,17 @@ The `co` prefix is accepted as an alias for `swarm`.
 | `crawl [url]` | Crawl from a URL or seed file. Supports `--seed-file`, `--sql`, `--sql-stdin`, `--sql-base64`, `--format`, `--output`, `-d/--depth`, `-ol/--out-link-selector`, `-olp/--out-link-pattern`, `-tl/--top-links`, `-a/--args`, `--refresh`, `--parse`, `--expires`, `-p/--priority`, `--page-load-timeout`, `--ignore-url-query`, `--no-norm`, `--readonly`, `-bg/--background`. |
 | `crawl status <id>` | Check crawl task status. |
 | `crawl result <id>` | Fetch crawl results. |
-| `crawl cancel <id>` | Cancel a running crawl. |
-| `crawl clear` | Remove terminal-state crawl tasks; supports force-style cleanup options. |
-| `crawl list` | List tracked crawl tasks. |
+| `crawl cancel <id>` | Cancel a running crawl (the checkpoint is kept, so it can be resumed). |
+| `crawl resume <id>` | Continue an interrupted crawl from its checkpoint: same task id, no repeat requests for URLs that already succeeded. `--retry-failed` re-fetches terminal failures; automatic resume at startup is off by default (`crawl.autoResume`). See [Crawl checkpoint & resume](docs/crawl-checkpoint-resume.md). |
+| `crawl clear` | Remove terminal-state crawl tasks; supports force-style cleanup options. Resumable checkpoints are kept until `crawl clear --all`. |
+| `crawl list` | List tracked crawl tasks (`--status interrupted` shows the resumable ones). |
 
 ```bash
 browser4-cli swarm create --max-open-tabs 12 --display-mode HEADLESS
 browser4-cli swarm query --seed-file urls.txt --sql @query.sql --refresh
 browser4-cli crawl "https://example.com" --depth 2 --out-link-selector "a[href]"
 browser4-cli crawl list
+browser4-cli crawl resume <task-id>    # continue an interrupted crawl
 ```
 
 #### Bundled skill files vs installed runtime skills
@@ -714,6 +724,13 @@ The runtime bundle is stored separately in a platform-conventional application-d
    that auto-build from source. Use `./b4w.ps1 <command>` (PowerShell),
    `./b4w.sh <command>` (Git Bash / Linux / macOS), or `./b4w.bat <command>`
    (CMD) — all accept the same arguments as the installed `browser4-cli` binary.
+   Dev mode only ever serves the checked-out code: a local runtime bundle built
+   from a **different project version** makes the command refuse to start (naming
+   the reason, the bundle's versions and build time, and the rebuild command)
+   rather than silently testing an outdated backend; a checkout whose sources
+   merely look newer than the bundle jars is rebuilt before the server starts —
+   see
+   [CLI install & upgrade](docs/cli-install-upgrade.md#dev-mode-the-backend-must-match-the-checkout).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser4-cli",
-  "version": "4.14.0-rc.6",
+  "version": "4.14.0-rc.7",
   "description": "Browser automation CLI for AI agents",
   "type": "module",
   "files": [

package/scripts/README.md

@@ -85,6 +85,8 @@ Runs a full CLI smoke test suitable for CI and local development:
 | `tests/install-browser4-cli.tests.sh` | Unit tests for the Unix install script |
 | `tests/install-browser4-cli.tests.ps1` | Unit tests for the Windows install script (Pester) |
 | `tests/wait-for-npm-version.tests.sh` | Unit tests for `wait-for-npm-version.sh` (stubbed `npm`, no network) |
+| `tests/reconcile-release-assets.tests.sh` | Unit tests for `reconcile-release-assets.sh` (stubbed `gh`, no network) |
+| `tests/wait-for-oss-sync.tests.sh` | Unit tests for `wait-for-oss-sync.sh` (stubbed `gh`, no network) |
 
 ## Publish (npm)
 
@@ -153,6 +155,70 @@ This makes the npm package README match the repository root README without leavi
 
 `postinstall.js` runs automatically after `npm install browser4-cli`. It detects the platform and downloads the matching native binary to `bin/`. On global installs, it also patches npm's bin shims to invoke the native binary directly.
 
+## Release
+
+| Script | Purpose |
+|--------|---------|
+| `reconcile-release-assets.sh` | Makes a GitHub release carry exactly the assets a job produced, re-uploading what is missing or truncated; called by `release.yml` after the publishing action |
+
+### Recovering from a failed release upload
+
+GitHub's release upload endpoint answers with a transient 5xx a few times a month
+(*"Error creating asset temp dir"*, *"Error saving asset"*, *"Unicorn!"*). v4.14.0-rc.6
+(`release.yml` run 35265014949) lost its whole release pipeline that way: the publishing
+action uploaded 6 of 11 assets and then failed, which skipped the artifact attestation, the
+release verification and the OSS sync.
+
+`reconcile-release-assets.sh` treats the release as the source of truth: it lists the assets
+the release carries, uploads only the files that are missing or whose size differs
+(`gh release upload --clobber`), and re-checks until the release matches or the budget
+expires. An already complete release costs one API call and no upload.
+
+```shell
+bash scripts/reconcile-release-assets.sh --tag v4.14.0 --repo platonai/Browser4 \
+  release-assets/Browser4.jar release-assets/browser4-cli-linux-x64
+bash scripts/reconcile-release-assets.sh --tag v4.14.0 --files-from release-assets.txt
+```
+
+Exit code 0 = the release carries every given file at the local size; 1 = still missing or
+mismatched when the budget (600 s by default) expired, the release does not exist, or bad
+usage. `release.yml` runs it in its own `Reconcile release assets` step, which decides
+whether that job passed — the publishing action runs with `continue-on-error: true` for
+exactly that reason.
+
+## Publish (release workflows)
+
+| Script | Platform | Purpose |
+|--------|----------|---------|
+| `wait-for-oss-sync.sh` | Linux/macOS | Triggers the `sync-to-oss.yml` workflow for a release tag and waits for **that** run; called by `release.yml` and `release-cli.yml` |
+
+### Verifying the OSS CDN sync
+
+GitHub Releases and the Alibaba Cloud OSS mirror are separate distribution channels: the OSS
+mirror is what `install-browser4-cli.sh` prefers in the China mainland, and its `latest`
+symlinks are what a plain "install the latest" resolves to. So the release should not report
+success while the mirror is still on the previous version — and it should not report failure
+just because the mirror is slow.
+
+`wait-for-oss-sync.sh` dispatches `sync-to-oss.yml` for the tag and waits for the run it
+**caused**, under a budget of its own:
+
+```shell
+bash scripts/wait-for-oss-sync.sh --tag v4.13.21              # 45 min budget, 15 s interval
+bash scripts/wait-for-oss-sync.sh --tag v4.13.21 --timeout 600 --interval 5
+bash scripts/wait-for-oss-sync.sh --tag v4.13.21 --repo platonai/Browser4
+```
+
+Exit code 0 = the run it triggered concluded `success`; 1 = that run failed, was cancelled,
+never appeared, or was still running when the budget expired. On failure and on timeout the
+message names the run, its URL, the step it is stuck on, and the commands to re-check
+(`gh run view <id>`) and re-trigger (`gh workflow run sync-to-oss.yml -f tag_name=<tag>`)
+it. It does **not** retry the sync itself: a re-triggered sync re-uploads every asset.
+
+Runs that already existed before the dispatch are excluded by id, so a previous release's
+successful sync can never be mistaken for the current one — the failure mode the old inline
+`gh run list --limit 1` loop had (see `docs-dev/copilot/ci-stabilization-4.13.x.md` §33).
+
 ## Documentation
 
 | Script | Platform | Purpose |

package/scripts/reconcile-release-assets.sh

@@ -0,0 +1,293 @@
+#!/bin/bash
+# ---------------------------------------------------------------------------
+# reconcile-release-assets.sh -- make a GitHub release carry exactly the
+# assets the build produced, retrying GitHub's transient upload failures
+# ---------------------------------------------------------------------------
+# Usage:
+#   reconcile-release-assets.sh --tag <tag> [--repo <owner/name>] \
+#       [--timeout <seconds>] [--interval <seconds>] [--settle <seconds>] \
+#       <file>...
+#   reconcile-release-assets.sh --tag <tag> [options] --files-from <path>
+#
+# Defaults: timeout 600 s, interval 30 s, settle 5 s.
+#
+# GitHub's release upload endpoint answers with a transient 5xx a few times a
+# month: "Error creating asset temp dir", "Error saving asset", "Unicorn!".
+# v4.14.0-rc.6 (release.yml run 35265014949) failed exactly this way -- the
+# "Publish GitHub release" job uploaded 6 of 11 assets and then died on
+#   ##[error]Error creating asset temp dir
+# which skipped the artifact attestation, the release verification and the
+# OSS sync: the whole release pipeline was lost to a server-side blip, with a
+# half-populated GitHub release left behind.
+#
+# GitHub does not say which upload failed, and a failed upload can leave a
+# partial asset behind, so re-running the whole upload is both slow and not
+# obviously correct. This script instead treats the release as the source of
+# truth and converges on it:
+#
+#   1. list the assets the release already carries (name and size),
+#   2. upload every local file that is missing or whose size differs, using
+#      `gh release upload --clobber` (which also replaces a partial asset),
+#   3. re-check, and repeat until the release matches the local files or the
+#      time budget runs out.
+#
+# It is idempotent: a release that already matches its files costs one API
+# call and no upload. Assets are matched by file name, which is the name the
+# publishing action uses for them. A release that does not exist is reported
+# as a failure rather than recreated here -- that is the release-creation
+# path, which the publishing action creates (and retries) with the workflow's
+# metadata.
+#
+# Exit codes:
+#   0  the release carries every given file with the local byte size
+#   1  still missing/mismatched when the budget expired, the release does not
+#      exist, a given file does not exist, or bad usage
+#
+# Designed for CI (GitHub Actions) but also runs on developer machines.
+# Requires `gh`, authenticated via GH_TOKEN/GITHUB_TOKEN or `gh auth login`.
+# ---------------------------------------------------------------------------
+set -euo pipefail
+
+TAG=''
+REPO=''
+TIMEOUT_SECONDS=600
+POLL_INTERVAL_SECONDS=30
+SETTLE_SECONDS=5
+FILES_FROM=''
+FILES=()
+
+usage() {
+    local code="${1:-1}"
+    {
+        echo "Usage: $0 --tag <tag> [--repo <owner/name>] [--timeout <seconds>]"
+        echo "          [--interval <seconds>] [--settle <seconds>]"
+        echo "          [--files-from <path>] <file>..."
+    } >&2
+    exit "$code"
+}
+
+while [ $# -gt 0 ]; do
+    case "${1:-}" in
+        --tag)
+            TAG="${2:-}"
+            shift 2 || usage
+            ;;
+        --repo)
+            REPO="${2:-}"
+            shift 2 || usage
+            ;;
+        --timeout)
+            TIMEOUT_SECONDS="${2:-}"
+            shift 2 || usage
+            ;;
+        --interval)
+            POLL_INTERVAL_SECONDS="${2:-}"
+            shift 2 || usage
+            ;;
+        --settle)
+            SETTLE_SECONDS="${2:-}"
+            shift 2 || usage
+            ;;
+        --files-from)
+            FILES_FROM="${2:-}"
+            shift 2 || usage
+            ;;
+        -h|--help)
+            usage 0
+            ;;
+        --)
+            shift
+            while [ $# -gt 0 ]; do
+                FILES+=("$1")
+                shift
+            done
+            ;;
+        -*)
+            echo "ERROR: unknown option '$1'" >&2
+            usage
+            ;;
+        *)
+            FILES+=("$1")
+            shift
+            ;;
+    esac
+done
+
+[ -n "$TAG" ] || { echo "ERROR: --tag is required" >&2; usage; }
+case "$TIMEOUT_SECONDS" in ''|*[!0-9]*) echo "ERROR: --timeout must be a whole number of seconds" >&2; usage ;; esac
+case "$POLL_INTERVAL_SECONDS" in ''|*[!0-9]*) echo "ERROR: --interval must be a whole number of seconds" >&2; usage ;; esac
+case "$SETTLE_SECONDS" in ''|*[!0-9]*) echo "ERROR: --settle must be a whole number of seconds" >&2; usage ;; esac
+[ "$POLL_INTERVAL_SECONDS" -gt 0 ] || { echo "ERROR: --interval must be at least 1 s" >&2; usage; }
+
+if [ -n "$FILES_FROM" ]; then
+    if [ ! -f "$FILES_FROM" ]; then
+        echo "ERROR: --files-from '$FILES_FROM' does not exist" >&2
+        exit 1
+    fi
+    # Newline-separated paths: the shape the publishing action's `files` input
+    # and this repository's release asset manifest already use.
+    while IFS= read -r manifest_line || [ -n "$manifest_line" ]; do
+        manifest_line="${manifest_line%$'\r'}"
+        [ -n "$manifest_line" ] || continue
+        FILES+=("$manifest_line")
+    done < "$FILES_FROM"
+fi
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+    echo "ERROR: no asset files given" >&2
+    usage
+fi
+
+for f in "${FILES[@]}"; do
+    if [ -z "$f" ]; then
+        echo "ERROR: empty asset file argument (is the asset list a real path list?)" >&2
+        exit 1
+    fi
+    if [ ! -f "$f" ]; then
+        echo "ERROR: asset file '$f' does not exist" >&2
+        exit 1
+    fi
+done
+
+if ! command -v gh >/dev/null 2>&1; then
+    echo "ERROR: gh is not installed -- https://cli.github.com" >&2
+    exit 1
+fi
+
+STDERR_FILE="$(mktemp)"
+trap 'rm -f "$STDERR_FILE"' EXIT
+
+# --repo is appended to the subcommand (gh declares it per command), so the two
+# call sites below branch instead of building an argument array that `set -u`
+# and old bash versions disagree about while it is empty.
+list_release_assets() {
+    if [ -n "$REPO" ]; then
+        gh release view "$TAG" --repo "$REPO" --json assets --jq '.assets[] | "\(.name) \(.size)"'
+    else
+        gh release view "$TAG" --json assets --jq '.assets[] | "\(.name) \(.size)"'
+    fi
+}
+
+upload_assets() {
+    if [ -n "$REPO" ]; then
+        gh release upload "$TAG" "$@" --repo "$REPO" --clobber
+    else
+        gh release upload "$TAG" "$@" --clobber
+    fi
+}
+
+local_size_of() {
+    wc -c < "$1" | tr -d '[:space:]'
+}
+
+# remote_size_of <name> -- size the release reports for <name>; returns 1 when
+# the release does not carry that asset. Asset names may contain spaces, so the
+# size is read as the last field of "name size".
+remote_size_of() {
+    local wanted="$1" line name size
+    while IFS= read -r line; do
+        [ -n "$line" ] || continue
+        name="${line% *}"
+        size="${line##* }"
+        if [ "$name" = "$wanted" ]; then
+            printf '%s' "$size"
+            return 0
+        fi
+    done <<< "$remote_listing"
+    return 1
+}
+
+started=$SECONDS
+attempt=0
+remote_listing=''
+gh_error=''
+
+while :; do
+    attempt=$((attempt + 1))
+    upload_status=1
+
+    set +e
+    remote_listing="$(list_release_assets 2>"$STDERR_FILE")"
+    status=$?
+    set -e
+
+    gh_error="$(head -n 1 "$STDERR_FILE" 2>/dev/null || true)"
+    elapsed=$((SECONDS - started))
+
+    if [ "$status" -eq 0 ]; then
+        NEEDED=()
+        REASONS=()
+        for f in "${FILES[@]}"; do
+            name="${f##*/}"
+            local_size="$(local_size_of "$f")"
+            if remote_size="$(remote_size_of "$name")"; then
+                if [ "$remote_size" = "$local_size" ]; then
+                    continue
+                fi
+                reason="size mismatch: the release has $remote_size bytes, the file has $local_size"
+            else
+                reason="missing from the release"
+            fi
+            NEEDED+=("$f")
+            REASONS+=("$reason")
+        done
+
+        if [ "${#NEEDED[@]}" -eq 0 ]; then
+            echo "Verified ${#FILES[@]} asset(s) on release $TAG after ${elapsed}s (attempt $attempt)"
+            exit 0
+        fi
+
+        echo "Uploading ${#NEEDED[@]} of ${#FILES[@]} asset(s) to release $TAG (attempt $attempt, ${elapsed}s elapsed):"
+        for i in "${!NEEDED[@]}"; do
+            echo "  - ${NEEDED[$i]##*/}: ${REASONS[$i]}"
+        done
+
+        set +e
+        upload_assets "${NEEDED[@]}" 2>&1 | sed 's/^/    /'
+        upload_status="${PIPESTATUS[0]}"
+        set -e
+
+        if [ "$upload_status" -ne 0 ]; then
+            echo "WARN: gh release upload failed (exit $upload_status) -- GitHub's upload endpoint returns a transient 5xx a few times a month ('Error creating asset temp dir', 'Error saving asset', 'Unicorn!'); retrying"
+        fi
+    else
+        if printf '%s' "$gh_error" | grep -qiE 'not found|HTTP 404'; then
+            echo "ERROR: release $TAG does not exist -- the publishing action failed before it could create the release" >&2
+            echo "ERROR: last GitHub answer: ${gh_error:-<no output>}" >&2
+            exit 1
+        fi
+        echo "WARN: could not list the assets of release $TAG (attempt $attempt, ${elapsed}s elapsed): ${gh_error:-<no output>}"
+    fi
+
+    remaining=$((TIMEOUT_SECONDS - elapsed))
+    if [ "$remaining" -le 0 ]; then
+        break
+    fi
+
+    # A finished upload round can stay invisible to the listing API for a
+    # moment; a short settle avoids re-uploading a file the release already
+    # has. A failed round waits the full interval before trying again.
+    if [ "$status" -eq 0 ] && [ "$upload_status" -eq 0 ]; then
+        delay="$SETTLE_SECONDS"
+    else
+        delay="$POLL_INTERVAL_SECONDS"
+    fi
+    # never sleep past the deadline: the total wait stays within the budget
+    if [ "$delay" -gt "$remaining" ]; then
+        sleep "$remaining"
+    elif [ "$delay" -gt 0 ]; then
+        sleep "$delay"
+    fi
+done
+
+echo "ERROR: release $TAG still does not match the build output after ${TIMEOUT_SECONDS}s" >&2
+for i in "${!NEEDED[@]}"; do
+    echo "ERROR:   - ${NEEDED[$i]##*/}: ${REASONS[$i]}" >&2
+done
+if [ -n "$gh_error" ]; then
+    echo "ERROR: last GitHub answer: ${gh_error}" >&2
+fi
+echo "ERROR: GitHub's release upload endpoint returns transient 5xx responses" >&2
+echo "ERROR: ('Error creating asset temp dir', 'Error saving asset', 'Unicorn!')." >&2
+echo "ERROR: Re-run the failed jobs of this workflow to retry the upload." >&2
+exit 1