browser4-cli 4.13.21 → 4.13.22

package/README.md

@@ -227,7 +227,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 |
@@ -281,7 +281,7 @@ 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. |
+| `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, stale daemon cleanup, optional repair. Supports `--verbose` and `--fix`. |
 | `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>`. |
@@ -522,15 +522,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

package/package.json

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

package/scripts/README.md

@@ -85,6 +85,7 @@ 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/wait-for-oss-sync.tests.sh` | Unit tests for `wait-for-oss-sync.sh` (stubbed `gh`, no network) |
 
 ## Publish (npm)
 
@@ -153,6 +154,39 @@ 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.
 
+## 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` §29).
+
 ## Documentation
 
 | Script | Platform | Purpose |

package/scripts/tests/wait-for-oss-sync.tests.sh

@@ -0,0 +1,382 @@
+#!/usr/bin/env bash
+# wait-for-oss-sync.tests.sh
+# Test suite for wait-for-oss-sync.sh
+# Uses only bash builtins and standard Unix tools -- no external test
+# frameworks and no network: `gh` is stubbed on PATH.
+#
+# Run:
+#   bash cli/scripts/tests/wait-for-oss-sync.tests.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT_UNDER_TEST="$(cd "$SCRIPT_DIR/.." && pwd)/wait-for-oss-sync.sh"
+
+PASS=0
+FAIL=0
+
+green()  { echo -e "\033[0;32m$*\033[0m"; }
+red()    { echo -e "\033[0;31m$*\033[0m"; }
+cyan()   { echo -e "\033[0;36m$*\033[0m"; }
+dim()    { echo -e "\033[2m$*\033[0m"; }
+
+# test <name> <command...>
+# The whole command is forwarded: `test "x" bash -c "..."` must not drop the
+# `-c "..."` part, or a bare `bash` would exit 0 and the assertion would pass
+# vacuously.
+test() {
+    local name="$1"
+    shift
+    if "$@"; then
+        PASS=$((PASS + 1))
+        green "  PASS  $name"
+    else
+        FAIL=$((FAIL + 1))
+        red   "  FAIL  $name"
+    fi
+}
+
+# ---- stub gh ----------------------------------------------------------
+#
+# The stub answers from files under $FAKE_GH_DIR, so every test reads as a
+# description of what GitHub was reporting:
+#
+#   baseline.tsv        `gh run list --limit 50`  (the pre-dispatch listing)
+#   baseline-fail       if present, that listing fails instead
+#   discover-<n>.tsv    n-th `gh run list --limit 20` (falls back to
+#   discover-last.tsv   ...discover-last.tsv, and to empty output)
+#   view-<n>.tsv        n-th `gh run view`           (falls back to
+#   view-last.tsv       ...view-last.tsv, and to empty output)
+#   dispatch-exit       exit status for `gh workflow run`
+#
+# Each file holds TSV exactly as the script's own -q filters produce it:
+#   run list : <databaseId>\t<createdAt>
+#   run view : <status>\t<conclusion>\t<in-progress step>
+# The script's own -q filters turn "no value" into "--" rather than leaving the
+# field empty (tab is IFS whitespace, so `read` would collapse the run of tabs
+# and an empty conclusion would swallow the step name).
+# An empty response stands for "gh could not answer", which is what the
+# script's `2>/dev/null` turns a failed call into.
+
+STUB_DIR="$(mktemp -d)"
+cleanup() { rm -rf "$STUB_DIR"; }
+trap cleanup EXIT
+
+cat > "$STUB_DIR/gh" <<'STUB'
+#!/usr/bin/env bash
+set -euo pipefail
+
+dir="${FAKE_GH_DIR:?FAKE_GH_DIR is required}"
+echo "$*" >> "$dir/calls.log"
+
+counter_next() {
+    local file="$dir/$1.count" n=0
+    if [ -f "$file" ]; then n="$(cat "$file")"; fi
+    n=$((n + 1))
+    printf '%s' "$n" > "$file"
+    printf '%s' "$n"
+}
+
+emit() {
+    # $1 = base name, $2 = sequence number: numbered response, else the fallback
+    local numbered="$dir/$1-$2.tsv" fallback="$dir/$1-last.tsv"
+    if [ -f "$numbered" ]; then
+        cat "$numbered"
+    elif [ -f "$fallback" ]; then
+        cat "$fallback"
+    fi
+    return 0
+}
+
+limit=''
+prev=''
+for arg in "$@"; do
+    if [ "$prev" = '--limit' ]; then limit="$arg"; fi
+    prev="$arg"
+done
+
+case "${1:-} ${2:-}" in
+    'run list')
+        if [ "$limit" = '50' ]; then
+            if [ -f "$dir/baseline-fail" ]; then exit 1; fi
+            if [ -f "$dir/baseline.tsv" ]; then cat "$dir/baseline.tsv"; fi
+        else
+            emit discover "$(counter_next list)"
+        fi
+        ;;
+    'run view')
+        emit view "$(counter_next view)"
+        ;;
+    'workflow run')
+        if [ -f "$dir/dispatch-exit" ]; then exit "$(cat "$dir/dispatch-exit")"; fi
+        ;;
+    *)
+        echo "fake gh: unhandled invocation: $*" >&2
+        exit 2
+        ;;
+esac
+STUB
+chmod +x "$STUB_DIR/gh"
+
+# ---- harness ----------------------------------------------------------
+
+RUN_STATUS=0
+RUN_OUTPUT=''
+
+# reset_gh -- empty the stub's response directory (and the call log)
+reset_gh() {
+    rm -rf "$STUB_DIR/gh-state"
+    mkdir -p "$STUB_DIR/gh-state"
+    export FAKE_GH_DIR="$STUB_DIR/gh-state"
+}
+
+# gh_respond <file> [<content>] -- write one stub response file
+gh_respond() {
+    local file="$1"
+    shift
+    if [ $# -gt 0 ]; then
+        printf '%s\n' "$*" > "$FAKE_GH_DIR/$file"
+    else
+        : > "$FAKE_GH_DIR/$file"
+    fi
+}
+
+# run_wait [<extra args>...] -- run the script on a 4 s / 1 s budget, so a
+# "never finishes" case costs ~4 s instead of the 2700 s default.
+run_wait() {
+    RUN_STATUS=0
+    RUN_OUTPUT="$(
+        FAKE_GH_DIR="$FAKE_GH_DIR" \
+        PATH="$STUB_DIR:$PATH" \
+        bash "$SCRIPT_UNDER_TEST" \
+            --tag v9.9.9 --repo acme/browser4 \
+            --timeout 4 --interval 1 --discovery-timeout 2 "$@" 2>&1
+    )" || RUN_STATUS=$?
+}
+
+# ---- pre-flight -------------------------------------------------------
+
+cyan  "============================================"
+cyan  " wait-for-oss-sync.sh Test Suite"
+cyan  "============================================"
+echo ""
+
+dim "--- Pre-flight ---"
+
+test "file exists" bash -c "[[ -f '$SCRIPT_UNDER_TEST' ]]"
+test "starts with shebang" bash -c "head -c 20 '$SCRIPT_UNDER_TEST' | grep -q '^#!/bin/bash'"
+test "bash syntax check passes" bash -c "bash -n '$SCRIPT_UNDER_TEST' 2>&1"
+test "no non-ASCII bytes" bash -c "! grep -Pn '[^\\x00-\\x7F]' '$SCRIPT_UNDER_TEST' >/dev/null 2>&1"
+test "--help exits 0 and prints usage" bash -c "bash '$SCRIPT_UNDER_TEST' --help 2>&1 | grep -q 'Usage:'"
+
+echo ""
+
+# ---- behaviour --------------------------------------------------------
+
+# The happy path, and the shape of the success message the workflows rely on.
+test_run_that_completes_successfully() {
+    reset_gh
+    gh_respond baseline.tsv "$(printf '111\t2026-09-20T15:20:51Z')"
+    gh_respond discover-last.tsv "$(printf '222\t2026-09-23T13:05:09Z')"
+    gh_respond view-1.tsv "$(printf 'in_progress\t--\tUpload to OSS')"
+    gh_respond view-last.tsv "$(printf 'completed\tsuccess\t--')"
+
+    run_wait
+    [ "$RUN_STATUS" -eq 0 ] || return 1
+    [[ "$RUN_OUTPUT" == *"Watching sync-to-oss.yml run 222"* ]] || return 1
+    [[ "$RUN_OUTPUT" == *"completed successfully"* ]] || return 1
+    [[ "$RUN_OUTPUT" == *"actions/runs/222"* ]] || return 1
+    grep -q 'workflow run sync-to-oss.yml' "$FAKE_GH_DIR/calls.log" || return 1
+}
+
+# The v4.13.17/v4.13.21 defect: the freshly dispatched run is not indexed yet,
+# so `gh run list` answers with the PREVIOUS release's run -- which completed
+# successfully.  Adopting it (the old inline loop did: first non-empty answer
+# won) reports the CDN as updated without waiting for anything.  Ours must win
+# even though the stale run is the more attractive answer.
+test_never_adopts_the_previous_runs_success() {
+    reset_gh
+    gh_respond baseline.tsv "$(printf '111\t2026-09-20T15:20:51Z')"
+    # both runs visible: 111 (before we dispatched, already green) and 222 (ours)
+    gh_respond discover-last.tsv "$(printf '222\t2026-09-23T13:05:09Z\n111\t2026-09-20T15:20:51Z')"
+    gh_respond view-last.tsv "$(printf 'completed\tfailure\t--')"
+
+    run_wait
+    [ "$RUN_STATUS" -eq 1 ] || return 1
+    # ours is named as the verdict ...
+    [[ "$RUN_OUTPUT" == *"run 222 concluded 'failure'"* ]] || return 1
+    # ... and the stale run's success was never claimed
+    [[ "$RUN_OUTPUT" != *"completed successfully"* ]] || return 1
+}
+
+# The same guard while our run is still queued behind the stale one.
+test_waits_for_our_run_when_only_stale_runs_are_listed() {
+    reset_gh
+    gh_respond baseline.tsv "$(printf '111\t2026-09-20T15:20:51Z')"
+    gh_respond discover-1.tsv "$(printf '111\t2026-09-20T15:20:51Z')"
+    gh_respond discover-2.tsv "$(printf '111\t2026-09-20T15:20:51Z')"
+    gh_respond discover-last.tsv "$(printf '222\t2026-09-23T13:05:09Z\n111\t2026-09-20T15:20:51Z')"
+    gh_respond view-last.tsv "$(printf 'completed\tsuccess\t--')"
+
+    # a generous discovery budget: the point is that it keeps looking, not
+    # that it finds the run on any particular poll
+    run_wait --discovery-timeout 20
+    [ "$RUN_STATUS" -eq 0 ] || return 1
+    [[ "$RUN_OUTPUT" == *"Watching sync-to-oss.yml run 222"* ]] || return 1
+    [[ "$RUN_OUTPUT" == *"Waiting for the sync-to-oss.yml run to appear"* ]] || return 1
+}
+
+# A dispatch that never becomes a run must be reported, not waited out.
+test_fails_when_no_new_run_appears() {
+    reset_gh
+    gh_respond baseline.tsv "$(printf '111\t2026-09-20T15:20:51Z')"
+    gh_respond discover-last.tsv "$(printf '111\t2026-09-20T15:20:51Z')"
+
+    run_wait
+    [ "$RUN_STATUS" -eq 1 ] || return 1
+    [[ "$RUN_OUTPUT" == *"no new run appeared within 2s"* ]] || return 1
+}
+
+# The v4.13.21 failure itself: the sync stalls, the budget expires.  The
+# message has to name the run, the step it is stuck on and how to re-check it
+# -- the old step timeout reported none of that.
+test_reports_the_stuck_run_when_the_budget_expires() {
+    reset_gh
+    gh_respond baseline.tsv "$(printf '111\t2026-09-20T15:20:51Z')"
+    gh_respond discover-last.tsv "$(printf '222\t2026-09-23T13:05:09Z')"
+    gh_respond view-last.tsv "$(printf 'in_progress\t--\tUpload to OSS')"
+
+    run_wait
+    [ "$RUN_STATUS" -eq 1 ] || return 1
+    [[ "$RUN_OUTPUT" == *"was still in_progress (step: Upload to OSS) after 4s"* ]] || return 1
+    [[ "$RUN_OUTPUT" == *"actions/runs/222"* ]] || return 1
+    [[ "$RUN_OUTPUT" == *"gh run view 222 --repo acme/browser4"* ]] || return 1
+    [[ "$RUN_OUTPUT" == *"gh workflow run sync-to-oss.yml --repo acme/browser4 -f tag_name=v9.9.9"* ]] || return 1
+    # the progress line names the stuck step too, so the log shows where it sat
+    [[ "$RUN_OUTPUT" == *"status=in_progress, step=Upload to OSS"* ]] || return 1
+}
+
+test_reports_a_failed_run() {
+    reset_gh
+    gh_respond baseline.tsv ''
+    gh_respond discover-last.tsv "$(printf '222\t2026-09-23T13:05:09Z')"
+    gh_respond view-last.tsv "$(printf 'completed\tfailure\t--')"
+
+    run_wait
+    [ "$RUN_STATUS" -eq 1 ] || return 1
+    [[ "$RUN_OUTPUT" == *"concluded 'failure'"* ]] || return 1
+    [[ "$RUN_OUTPUT" == *"actions/runs/222"* ]] || return 1
+}
+
+test_reports_a_cancelled_run_as_a_failure() {
+    reset_gh
+    gh_respond baseline.tsv ''
+    gh_respond discover-last.tsv "$(printf '222\t2026-09-23T13:05:09Z')"
+    gh_respond view-last.tsv "$(printf 'completed\tcancelled\t--')"
+
+    run_wait
+    [ "$RUN_STATUS" -eq 1 ] || return 1
+    [[ "$RUN_OUTPUT" == *"concluded 'cancelled'"* ]] || return 1
+}
+
+# An unreadable poll (rate limit, network blip) must not abort the wait: the
+# stub answers nothing for the first view call, then reports our run done.
+test_survives_an_unreadable_poll() {
+    reset_gh
+    gh_respond baseline.tsv ''
+    gh_respond discover-last.tsv "$(printf '222\t2026-09-23T13:05:09Z')"
+    gh_respond view-1.tsv ''
+    gh_respond view-last.tsv "$(printf 'completed\tsuccess\t--')"
+
+    run_wait
+    [ "$RUN_STATUS" -eq 0 ] || return 1
+    [[ "$RUN_OUTPUT" == *"completed successfully"* ]] || return 1
+}
+
+test_fails_when_the_dispatch_itself_fails() {
+    reset_gh
+    gh_respond baseline.tsv ''
+    printf '1' > "$FAKE_GH_DIR/dispatch-exit"
+
+    run_wait
+    [ "$RUN_STATUS" -eq 1 ] || return 1
+    [[ "$RUN_OUTPUT" == *"Could not dispatch sync-to-oss.yml"* ]] || return 1
+}
+
+# With the baseline listing unavailable the run is identified by creation time
+# alone -- a run created after the dispatch is still accepted ...
+test_falls_back_to_creation_time_when_the_baseline_listing_fails() {
+    reset_gh
+    : > "$FAKE_GH_DIR/baseline-fail"
+    gh_respond discover-last.tsv "$(printf '222\t2099-01-01T00:00:00Z')"
+    gh_respond view-last.tsv "$(printf 'completed\tsuccess\t--')"
+
+    run_wait
+    [ "$RUN_STATUS" -eq 0 ] || return 1
+    [[ "$RUN_OUTPUT" == *"could not list existing sync-to-oss.yml runs"* ]] || return 1
+    [[ "$RUN_OUTPUT" == *"Watching sync-to-oss.yml run 222"* ]] || return 1
+}
+
+# ... and a run from before the dispatch is not, even with no id baseline.
+test_creation_time_fallback_still_refuses_a_stale_run() {
+    reset_gh
+    : > "$FAKE_GH_DIR/baseline-fail"
+    gh_respond discover-last.tsv "$(printf '111\t2020-01-01T00:00:00Z')"
+    gh_respond view-last.tsv "$(printf 'completed\tsuccess\t--')"
+
+    run_wait
+    [ "$RUN_STATUS" -eq 1 ] || return 1
+    [[ "$RUN_OUTPUT" == *"no new run appeared"* ]] || return 1
+}
+
+test_requires_the_tag_argument() {
+    local output status
+    output="$(PATH="$STUB_DIR:$PATH" bash "$SCRIPT_UNDER_TEST" --repo acme/browser4 2>&1)" && status=0 || status=$?
+    [ "$status" -ne 0 ] || return 1
+    [[ "$output" == *"Usage:"* ]] || return 1
+    [[ "$output" == *"--tag is required"* ]] || return 1
+}
+
+test_rejects_an_unknown_argument() {
+    local output status
+    output="$(PATH="$STUB_DIR:$PATH" bash "$SCRIPT_UNDER_TEST" --tag v1 --nonsense 2>&1)" && status=0 || status=$?
+    [ "$status" -ne 0 ] || return 1
+    [[ "$output" == *"unknown argument '--nonsense'"* ]] || return 1
+}
+
+test_rejects_a_non_numeric_timeout() {
+    local output status
+    output="$(PATH="$STUB_DIR:$PATH" bash "$SCRIPT_UNDER_TEST" --tag v1 --timeout soon 2>&1)" && status=0 || status=$?
+    [ "$status" -ne 0 ] || return 1
+    [[ "$output" == *"--timeout must be a whole number"* ]] || return 1
+}
+
+dim "--- Behaviour ---"
+
+test "run completes successfully" test_run_that_completes_successfully
+test "never adopts the previous run's success" test_never_adopts_the_previous_runs_success
+test "waits for our run when only stale runs are listed" test_waits_for_our_run_when_only_stale_runs_are_listed
+test "fails when no new run appears" test_fails_when_no_new_run_appears
+test "reports the stuck run when the budget expires" test_reports_the_stuck_run_when_the_budget_expires
+test "reports a failed run" test_reports_a_failed_run
+test "reports a cancelled run as a failure" test_reports_a_cancelled_run_as_a_failure
+test "survives an unreadable poll" test_survives_an_unreadable_poll
+test "fails when the dispatch itself fails" test_fails_when_the_dispatch_itself_fails
+test "falls back to creation time when the baseline listing fails" test_falls_back_to_creation_time_when_the_baseline_listing_fails
+test "creation-time fallback still refuses a stale run" test_creation_time_fallback_still_refuses_a_stale_run
+test "requires the tag argument" test_requires_the_tag_argument
+test "rejects an unknown argument" test_rejects_an_unknown_argument
+test "rejects a non-numeric timeout" test_rejects_a_non_numeric_timeout
+
+# ---- summary ----------------------------------------------------------
+
+echo ""
+cyan "============================================"
+if [ "$FAIL" -eq 0 ]; then
+    green " All $PASS tests passed"
+else
+    red   " $FAIL of $((PASS + FAIL)) tests failed"
+fi
+cyan "============================================"
+
+[ "$FAIL" -eq 0 ]

package/scripts/wait-for-oss-sync.sh

@@ -0,0 +1,314 @@
+#!/bin/bash
+# ---------------------------------------------------------------------------
+# wait-for-oss-sync.sh -- trigger the Aliyun OSS sync for a release tag and
+# wait for that exact run to finish
+# ---------------------------------------------------------------------------
+# Usage:
+#   wait-for-oss-sync.sh --tag <tag> [--repo <owner/name>] [--workflow <name>]
+#                        [--timeout <seconds>] [--interval <seconds>]
+#                        [--discovery-timeout <seconds>]
+#
+# Defaults: --workflow sync-to-oss.yml, --timeout 3900 s, --interval 15 s,
+#           --discovery-timeout 120 s.
+#
+# release.yml and release-cli.yml used to inline this whole dance:
+#
+#     gh workflow run sync-to-oss.yml -f tag_name="$TAG"
+#     sleep 3
+#     RUN_ID=$(gh run list --workflow=sync-to-oss.yml --limit 1 ...)  # nothing but air for 20 tries
+#     gh run watch "$RUN_ID" --exit-status
+#
+# under a step `timeout-minutes: 15`.  Three things were wrong with it:
+#
+#   1. The run it waited on was not necessarily the run it triggered.  `gh run
+#      list` answers newest-first, so while the freshly dispatched run was not
+#      indexed yet the loop's first non-empty answer was the PREVIOUS release's
+#      sync run -- already completed, conclusion "success".  The step then
+#      reported the CDN as updated without having waited for the current sync
+#      at all.  Same defect class as bd18d2b7d8, which fixed the identical
+#      run-discovery race in monitor-release.ps1.
+#   2. The wait had no budget of its own.  The only bound was the step timeout,
+#      which kills the step and reports
+#        "The action 'Sync to Aliyun OSS CDN' has timed out after 15 minutes."
+#      -- no run id, no run URL, and no statement of what the sync was doing.
+#   3. `gh run watch` re-renders the entire run every 3 s: a wall of text that
+#      still never says which step the sync is stuck on.
+#
+# v4.13.21 (release.yml run 35860129386) hit all three at once.  The sync run's
+# "Upload to OSS" step stalled -- 18+ minutes and still counting, against ~2
+# minutes for the same 11 assets in every earlier release -- the 15-minute cap
+# fired, and the release job went red after everything had in fact been
+# published to GitHub, npm and the container registries.
+#
+# So this script:
+#
+#   1. records the sync runs that already exist BEFORE dispatching, and only
+#      ever accepts a run that is not one of them (or, when that listing
+#      failed, one created after the newest of them) -- a stale run can never
+#      be mistaken for ours,
+#   2. waits under an explicit budget of its own, never sleeping past the
+#      deadline, and
+#   3. reports the run id, the run URL, the elapsed time and the step the run
+#      is currently on -- on success, on failure, and on timeout alike.
+#
+# It deliberately does not retry the sync: a re-triggered sync re-uploads every
+# asset.  The verdict belongs to the caller; re-run the workflow (or this
+# script) once the run it names has been looked at.
+#
+# Exit codes:
+#   0  the sync run this script triggered completed successfully
+#   1  that run failed, was cancelled, never appeared, or was still running
+#      when the budget expired -- 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=''
+WORKFLOW='sync-to-oss.yml'
+# 65 min: above sync-to-oss.yml's worst case (job 60 min) plus queue time, so the
+# waiter reports the sync's verdict instead of expiring first.  Sized for a
+# re-sync, where the destination objects already exist and the transfer runs at
+# roughly a tenth of a first sync's speed.
+TIMEOUT_SECONDS=3900
+POLL_INTERVAL_SECONDS=15
+DISCOVERY_TIMEOUT_SECONDS=120
+
+usage() {
+    local code="${1:-1}"
+    {
+        echo "Usage: $0 --tag <tag> [--repo <owner/name>] [--workflow <name>]"
+        echo "          [--timeout <seconds>] [--interval <seconds>]"
+        echo "          [--discovery-timeout <seconds>]"
+    } >&2
+    exit "$code"
+}
+
+while [ $# -gt 0 ]; do
+    case "${1:-}" in
+        --tag)
+            TAG="${2:-}"
+            shift 2 || usage
+            ;;
+        --repo)
+            REPO="${2:-}"
+            shift 2 || usage
+            ;;
+        --workflow)
+            WORKFLOW="${2:-}"
+            shift 2 || usage
+            ;;
+        --timeout)
+            TIMEOUT_SECONDS="${2:-}"
+            shift 2 || usage
+            ;;
+        --interval)
+            POLL_INTERVAL_SECONDS="${2:-}"
+            shift 2 || usage
+            ;;
+        --discovery-timeout)
+            DISCOVERY_TIMEOUT_SECONDS="${2:-}"
+            shift 2 || usage
+            ;;
+        -h|--help)
+            usage 0
+            ;;
+        *)
+            echo "ERROR: unknown argument '$1'" >&2
+            usage
+            ;;
+    esac
+done
+
+[ -n "$TAG" ] || { echo "ERROR: --tag is required" >&2; usage; }
+[ -n "$WORKFLOW" ] || { echo "ERROR: --workflow must not be empty" >&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 "$DISCOVERY_TIMEOUT_SECONDS" in ''|*[!0-9]*) echo "ERROR: --discovery-timeout must be a whole number of seconds" >&2; usage ;; esac
+[ "$TIMEOUT_SECONDS" -gt 0 ] || { echo "ERROR: --timeout must be at least 1 s" >&2; usage; }
+[ "$POLL_INTERVAL_SECONDS" -gt 0 ] || { echo "ERROR: --interval must be at least 1 s" >&2; usage; }
+
+repo_label="${REPO:-<current repo>}"
+
+# gh reads --repo per subcommand, so append it rather than building an argument
+# list: an empty array under `set -u` is a portability trap older bash and
+# GitHub's runners disagree about.
+gh_ws() {
+    if [ -n "$REPO" ]; then
+        gh "$@" --repo "$REPO"
+    else
+        gh "$@"
+    fi
+}
+
+# The most recent runs of the sync workflow, newest first, as TSV.
+# `limit` is a parameter because the pre-dispatch listing wants a long memory
+# (every run that can be mistaken for ours) while the discovery poll only ever
+# looks at the newest few.  Fails (non-zero) when gh cannot answer, so the
+# caller can tell "no runs yet" from "the listing is unavailable".
+list_runs_tsv() {
+    gh_ws run list --workflow="$WORKFLOW" --limit "$1" \
+        --json databaseId,createdAt -q '.[] | [.databaseId, .createdAt] | @tsv' 2>/dev/null
+}
+
+# status, conclusion and the step the run is currently on, as TSV.
+#
+# "--" stands for "no value": a bare empty tab-separated field is not
+# survivable here, because tab is IFS whitespace, so `read` collapses a run of
+# tabs and an empty conclusion would silently swallow the step name (which is
+# exactly the diagnostic this script exists to report).
+view_run_tsv() {
+    local run_id="$1"
+    gh_ws run view "$run_id" --json status,conclusion,jobs \
+        -q '[.status, (.conclusion // "--"), ([.jobs[].steps[]? | select(.status == "in_progress") | .name] | join(",") | if . == "" then "--" else . end)] | @tsv' 2>/dev/null || true
+}
+
+# ---- 1. what the sync workflow looks like before we add to it --------------
+
+baseline_ok=true
+baseline_tsv=''
+if ! baseline_tsv="$(list_runs_tsv 50)"; then
+    baseline_ok=false
+    baseline_tsv=''
+fi
+
+baseline_ids=' '
+watermark_created=''
+while IFS=$'\t' read -r _id _created; do
+    [ -n "${_id:-}" ] || continue
+    baseline_ids="${baseline_ids}${_id} "
+done <<< "$baseline_tsv"
+
+if [ "$baseline_ok" != true ]; then
+    # No id baseline to compare against, so our run is identified by creation
+    # time alone: anything created after this dispatch watermark is a
+    # candidate.  The watermark is local, so a stale run could only slip
+    # through by being created in the same second as our dispatch -- which
+    # would be a sync of the same release anyway.
+    watermark_created="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    echo "WARN: could not list existing ${WORKFLOW} runs; identifying our run by creation time alone (after ${watermark_created})"
+fi
+echo "Existing ${WORKFLOW} runs to exclude: $(printf '%s' "$baseline_ids" | wc -w)"
+
+# ---- 2. dispatch ----------------------------------------------------------
+
+echo "Triggering ${WORKFLOW} for ${TAG}"
+if ! gh_ws workflow run "$WORKFLOW" -f tag_name="$TAG"; then
+    echo "::error::Could not dispatch ${WORKFLOW} for ${TAG} in ${repo_label} -- check that the workflow exists on the default branch and that the token may run it."
+    exit 1
+fi
+
+# ---- 3. find OUR run, never an older one ----------------------------------
+
+RUN_ID=''
+RUN_URL=''
+discovery_started=$SECONDS
+attempt=0
+
+while :; do
+    attempt=$((attempt + 1))
+    rows="$(list_runs_tsv 20)" || rows=''
+
+    while IFS=$'\t' read -r run_id created_at; do
+        [ -n "${run_id:-}" ] || continue
+        # Never accept a run that existed before we dispatched.  With the id
+        # baseline in hand that test is exact and involves no clock at all;
+        # only when that listing failed do we fall back to the creation-time
+        # watermark taken just before the dispatch.
+        if [ "$baseline_ok" = true ]; then
+            if [[ "$baseline_ids" == *" ${run_id} "* ]]; then
+                continue
+            fi
+        elif [[ "$created_at" < "$watermark_created" ]]; then
+            continue
+        fi
+        RUN_ID="$run_id"
+        RUN_URL="https://github.com/${REPO:-platonai/Browser4}/actions/runs/${run_id} (created ${created_at})"
+        break
+    done <<< "$rows"
+
+    if [ -n "$RUN_ID" ]; then
+        break
+    fi
+
+    elapsed=$((SECONDS - discovery_started))
+    remaining=$((DISCOVERY_TIMEOUT_SECONDS - elapsed))
+    if [ "$remaining" -le 0 ]; then
+        break
+    fi
+    echo "Waiting for the ${WORKFLOW} run to appear (attempt ${attempt}, ${remaining}s left)"
+    if [ "$POLL_INTERVAL_SECONDS" -gt "$remaining" ]; then
+        sleep "$remaining"
+    else
+        sleep "$POLL_INTERVAL_SECONDS"
+    fi
+done
+
+if [ -z "$RUN_ID" ]; then
+    echo "::error::${WORKFLOW} was dispatched for ${TAG} but no new run appeared within ${DISCOVERY_TIMEOUT_SECONDS}s."
+    echo "::error::Check https://github.com/${REPO:-platonai/Browser4}/actions/workflows/${WORKFLOW} -- the run may have been refused before it was queued."
+    exit 1
+fi
+
+RUN_URL="https://github.com/${REPO:-platonai/Browser4}/actions/runs/${RUN_ID}"
+echo "Watching ${WORKFLOW} run ${RUN_ID} for ${TAG}: ${RUN_URL}"
+
+# ---- 4. wait for it, under our own budget ---------------------------------
+
+status='unknown'
+conclusion=''
+stuck_on=''
+last_state=''
+last_reported_at=-60
+wait_started=$SECONDS
+
+while :; do
+    now=$((SECONDS - wait_started))
+
+    line="$(view_run_tsv "$RUN_ID")"
+    if [ -n "$line" ]; then
+        status=''; conclusion=''; stuck_on=''
+        IFS=$'\t' read -r status conclusion stuck_on <<< "$line" || true
+        [ "$conclusion" != '--' ] || conclusion=''
+        [ "$stuck_on" != '--' ] || stuck_on=''
+    fi
+    # An unreadable poll (rate limit, network blip) keeps the last known state
+    # and simply counts against the budget -- it must not abort the wait.
+
+    state="${status}|${stuck_on}"
+    remaining=$((TIMEOUT_SECONDS - now))
+    if [ "$state" != "$last_state" ] || [ $((now - last_reported_at)) -ge 60 ]; then
+        echo "run ${RUN_ID}: status=${status:-unknown}${stuck_on:+, step=${stuck_on}} (${now}s elapsed, ${remaining}s left)"
+        last_state="$state"
+        last_reported_at="$now"
+    fi
+
+    if [ "$status" = 'completed' ]; then
+        if [ "$conclusion" = 'success' ]; then
+            echo "Aliyun OSS CDN sync for ${TAG} completed successfully"
+            echo "Run URL: ${RUN_URL}"
+            exit 0
+        fi
+        echo "::error::${WORKFLOW} run ${RUN_ID} concluded '${conclusion:-unknown}' -- the OSS CDN may still serve an older release."
+        echo "::error::Run URL: ${RUN_URL}"
+        echo "::error::Re-check it, then re-trigger with: gh workflow run ${WORKFLOW} -f tag_name=${TAG}"
+        exit 1
+    fi
+
+    if [ "$remaining" -le 0 ]; then
+        break
+    fi
+    if [ "$POLL_INTERVAL_SECONDS" -gt "$remaining" ]; then
+        sleep "$remaining"
+    else
+        sleep "$POLL_INTERVAL_SECONDS"
+    fi
+done
+
+echo "::error::${WORKFLOW} run ${RUN_ID} was still ${status:-unknown}${stuck_on:+ (step: ${stuck_on})} after ${TIMEOUT_SECONDS}s -- the OSS CDN was not confirmed updated for ${TAG}."
+echo "::error::Run URL: ${RUN_URL}"
+echo "::error::Re-check it with: gh run view ${RUN_ID}${REPO:+ --repo $REPO}"
+echo "::error::Then re-trigger with: gh workflow run ${WORKFLOW}${REPO:+ --repo $REPO} -f tag_name=${TAG}"
+exit 1