Fix seven medium-severity bugs from the full-session code review

- SupplierOffer::insert(): now checks $wpdb->insert()'s return value and
  throws, matching Work/Edition/Isbn (the one Catalog class that hadn't
  been hardened this way). Work::set_product_id() gets the same treatment
  (was flagged low-severity but same fix, bundled here) — a real update
  failure now counts as a per-work sync failure instead of silently
  leaving a stale wc_product_id pointer.

- SupplierOffer: fetched_at was written via current_time('mysql') (site-
  local) while expires_at (SyntheticOfferGenerator) is written in UTC, and
  best_offer_for_isbns() compared against site-local time too — a mismatch
  masked today only because dev's gmt_offset is 0. Switched both writer and
  reader to current_time('mysql', true) (UTC). Verified the read path
  still finds all active offers correctly under a simulated -5 (US
  Eastern) offset, not just at offset 0.

- HardcoverAdapter: rate-limit throttling moved from "once per work" (in
  Commands.php) to "once per actual HTTP request" (inside query() itself).
  find_book()'s ISBN-then-title/author fallback can fire two real requests
  per work — under the old scheme both shared one throttle sleep, roughly
  doubling the real request rate against a beta API. query() also now
  retries network errors/5xx/429 up to 3x (mirroring
  OpenLibraryAdapter::get_with_retry()), while a GraphQL-level `errors` field
  or other 4xx throws immediately (retrying a rejected query can't fix it).
  Commands.php adds a 5-consecutive-failure circuit breaker so a bad token
  or a wrong field in the still-unverified schema can't silently burn
  through the whole catalog with zero progress. Verified all of this
  directly against Hardcover's real API with a deliberately invalid token:
  5 fast (non-retried) 401s, correct abort message, and confirmed the
  failed works were NOT marked synced (so a real token can retry them).

- restore.sh: now drops and recreates the target database before restoring
  the dump, and clears the uploads directory before extracting the
  archive — previously both restored on top of existing state, so a stray
  table or file NOT in the backup would silently survive a restore drill.
  Verified end-to-end against a real local staging stack: planted a stray
  table and a stray upload file after taking a backup, ran restore.sh, and
  confirmed both were gone afterward while the actual backed-up data (20
  works, a known upload file) came back correctly. Also fixed a real
  permission gap hit during that same test: a fresh volume's uploads dir
  is root-owned until something chowns it, which broke the new www-data
  clear step — now clears as root and chowns to www-data afterward, which
  also means restore self-heals the exact root-owned-uploads class of bug
  fixed earlier this session for the cron sidecar.

- poll-deploy.sh: added a non-blocking flock so a deploy that runs longer
  than the cron interval can't have a second poll fire mid-deploy and race
  its git checkout/reset against the same live working tree. Verified: a
  concurrent run correctly skips instantly while the lock is held, and
  proceeds normally once it's released. (Full atomicity of the live PHP
  file swap under real traffic is a bigger architectural question —
  blue-green or symlinked releases — flagged to the user rather than
  attempted here.)

- backup.sh: now also archives .env.<environment> itself (chmod 600) and
  includes it in the off-host rclone sync alongside the DB dump and
  uploads archive. Every API key and both DB passwords previously lived
  only on the host in this one gitignored file — losing the host lost all
  of it even with DB/uploads backups intact.

deploy/backup.sh

@@ -42,10 +42,22 @@ echo "==> archiving uploads"
 $COMPOSE run --rm -T -u www-data wordpress tar -czf - -C /var/www/html/wp-content uploads \
   > "$BACKUP_DIR/uploads-${TIMESTAMP}.tar.gz"
 
+echo "==> archiving environment config"
+# Every API key (Booksrun/Ingram/Helcim/MailerLite/Hardcover), the WP admin
+# bootstrap credentials, and both DB passwords live ONLY in this one
+# gitignored host file — losing the host without this backed up loses all of
+# it, even with the DB dump and uploads intact. Same trust model as the DB
+# dump above (also plaintext, also only as protected as $BACKUP_DIR/
+# $BACKUP_REMOTE are) — chmod 600 since, unlike the DB/uploads archives, this
+# one is directly the credentials themselves, not data that merely contains some.
+cp "$ENV_FILE" "$BACKUP_DIR/env-${TIMESTAMP}"
+chmod 600 "$BACKUP_DIR/env-${TIMESTAMP}"
+
 if [[ -n "${BACKUP_REMOTE:-}" ]]; then
   echo "==> syncing to off-host storage ($BACKUP_REMOTE)"
   rclone copy "$BACKUP_DIR/db-${TIMESTAMP}.sql.gz" "$BACKUP_REMOTE/${ENVIRONMENT}/"
   rclone copy "$BACKUP_DIR/uploads-${TIMESTAMP}.tar.gz" "$BACKUP_REMOTE/${ENVIRONMENT}/"
+  rclone copy "$BACKUP_DIR/env-${TIMESTAMP}" "$BACKUP_REMOTE/${ENVIRONMENT}/"
 else
   echo "==> BACKUP_REMOTE not set — backup stayed local only; configure rclone before launch"
 fi

deploy/poll-deploy.sh

@@ -13,6 +13,20 @@ ENVIRONMENT="${1:?Usage: poll-deploy.sh <staging|production>}"
 REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$REPO_ROOT"
 
+# A deploy (docker compose up --build + full WP/plugin install) can run
+# longer than the cron interval on modest hardware, and the git
+# checkout/reset below writes directly onto the live working tree that's
+# bind-mounted into the running containers — a second poll firing mid-deploy
+# would race the first one's file writes. Non-blocking: if one's already
+# running, this run just skips (the next poll picks up wherever HEAD ends up),
+# rather than queuing up concurrent deploys.
+LOCK_FILE="${REPO_ROOT}/.poll-deploy-${ENVIRONMENT}.lock"
+exec 200>"$LOCK_FILE"
+if ! flock -n 200; then
+  echo "$(date -Is) deploy already in progress for ${ENVIRONMENT}, skipping this poll"
+  exit 0
+fi
+
 case "$ENVIRONMENT" in
   staging)    BRANCH=staging ;;
   production) BRANCH=main ;;

deploy/restore.sh

@@ -11,6 +11,10 @@ cd "$REPO_ROOT"
 
 ENV_FILE=".env.staging"
 export ENVIRONMENT=staging
+# shellcheck source=lib/env.sh
+source "$REPO_ROOT/deploy/lib/env.sh"
+DB_NAME_VALUE="$(env_get "$ENV_FILE" DB_NAME)"
+: "${DB_NAME_VALUE:?set DB_NAME in ${ENV_FILE}}"
 
 # See deploy.sh for why: Compose warns on any $-shaped value in --env-file
 # even when unused, so DB_PASSWORD/DB_ROOT_PASSWORD are filtered out of the
@@ -25,9 +29,32 @@ echo "!! this OVERWRITES the staging database and uploads !!"
 read -r -p "type 'restore' to continue: " confirm
 [[ "$confirm" == "restore" ]] || { echo "aborted"; exit 1; }
 
+echo "==> dropping and recreating the staging database for a clean restore"
+# Without this, a table present in staging but absent from the dump (a stray
+# leftover from before a schema change, a one-off test table) would silently
+# survive "restore" and go undetected — a drill could pass while masking data
+# genuinely missing from the backup. Grants tied to a non-root user are keyed
+# to the database NAME in MariaDB's privilege tables, not the schema object's
+# identity, so MARIADB_USER's access survives a same-name drop+recreate
+# (verified directly against a throwaway database before relying on this).
+$COMPOSE exec -T db sh -c "exec mariadb -u root -p\"\$(cat /run/secrets/db_root_password)\" -e 'DROP DATABASE IF EXISTS \`${DB_NAME_VALUE}\`; CREATE DATABASE \`${DB_NAME_VALUE}\`;'"
+
 echo "==> restoring database"
 gunzip -c "$DB_DUMP" | $COMPOSE exec -T db sh -c "exec mariadb -u\"\$MARIADB_USER\" -p\"\$(cat /run/secrets/db_password)\" \"\$MARIADB_DATABASE\""
 
+echo "==> clearing existing uploads before restoring"
+# Same reasoning as the database above: extracting on top of whatever's
+# already there would let a file missing from the archive hide behind one
+# that happens to still be present from before the drill. Runs as root
+# (unlike the tar extraction below), not www-data: the uploads directory
+# itself can be root:root on a volume that's never had a www-data-owned
+# write land in it yet (the official image's entrypoint creates it on first
+# boot, before dropping to www-data) — confirmed directly against a fresh
+# staging volume. chown afterward so the subsequent www-data tar extraction
+# below can actually write into it.
+$COMPOSE run --rm -T wordpress sh -c \
+  "find /var/www/html/wp-content/uploads -mindepth 1 -delete && chown www-data:www-data /var/www/html/wp-content/uploads"
+
 echo "==> restoring uploads"
 ARCHIVE_DIR="$(cd "$(dirname "$UPLOADS_ARCHIVE")" && pwd)"
 ARCHIVE_NAME="$(basename "$UPLOADS_ARCHIVE")"