@oneie/claude 0.7.0 → 0.8.0

package/scripts/deploy.sh

@@ -0,0 +1,1037 @@
+#!/usr/bin/env bash
+# Deterministic /deploy — the whole pipeline with no LLM in the loop.
+#
+# Ships the five services to Cloudflare: gateway (api) · sync · channels ·
+# pay/backend · astro (one-prod). Every step reports a number; the final
+# report is the same shape /deploy prints by hand.
+#
+# Usage:
+#   bash .claude/scripts/deploy.sh dev             # one.ie/web → one-dev (dev.one.ie)
+#   bash .claude/scripts/deploy.sh                 # full pipeline (PRODUCTION)
+#   bash .claude/scripts/deploy.sh astro           # one.ie/web → one-prod only
+#   bash .claude/scripts/deploy.sh workers         # api + sync + channels
+#   bash .claude/scripts/deploy.sh gateway|sync|agents|pay
+#
+# Flags:
+#   --skip-tests      skip vitest (typecheck still runs)
+#   --no-typedb-flake-waiver
+#                     hard-stop on a red suite even when every failure is the
+#                     shared TypeDB Cloud cluster being unreachable. The waiver
+#                     is ON by default (DEPLOY_ALLOW_TYPEDB_FLAKE=0 also disables)
+#                     and is classified by signature — a real assertion break, or
+#                     a tasks:claim `not_found`, still blocks.
+#   --skip-typecheck  skip per-service tsc
+#   --skip-build      reuse an existing one.ie/web/dist
+#   --skip-migrations skip `d1 migrations apply DB --remote`
+#   --skip-health     deploy without the post-deploy probes
+#   --changed         skip services with no commits since their last deploy
+#   --gates-only      run the gates, ship nothing (a local pre-flight)
+#   --check-creds     self-test the credential ladder, ship nothing
+#   --yes / -y        no approval prompt (also: DEPLOY_YES=1)
+#   --dry-run         print every command, deploy nothing
+#
+# NOT done here (it needs judgment): commit / PR / merge. Commit before you
+# run this. The script refuses a dirty tree unless --allow-dirty.
+#
+# HARD RULES baked in (see .claude/commands/deploy.md):
+#   · never `--env production` — it ships to the `one-prod-production` decoy
+#   · CLOUDFLARE_API_TOKEN is unset; auth is GLOBAL_API_KEY + EMAIL
+#   · health-check custom domains only (*.workers.dev is blocked on this net)
+#   · sync is cron-only: a clean `wrangler deploy` IS its health signal
+#
+# THE TWO TIERS — one command, two destinations:
+#   dev   → https://dev.one.ie (worker `one-dev`). Agents finish loops here.
+#           MINIMUM gate: the FAST lane. No approval prompt, no migrations, no
+#           five-service fan-out. Delegates to deploy-dev.sh, which is the
+#           authority for the dev procedure.
+#   prod  → https://one.ie and the other four services. FULL gate always
+#           (FULL_VERIFY=1), approval prompt unless --yes.
+# A fast pass is NEVER reported as a full pass, and `dev` never touches prod.
+# dev.one.ie shares PRODUCTION's D1 and KV byte-for-byte — only the cron strip
+# differs. So a dev deploy is NOT a sandbox for data: it reads and writes the
+# same rows one.ie does. Ship dev freely; treat its DATA as production.
+
+set -uo pipefail
+
+# The deploy gate is the FULL gate, always. Build cycles run the dev lane
+# (verify:fast — tsc + related tests + pinned suites); this is the one place
+# every test must run, so any script that honours FULL_VERIFY runs everything.
+export FULL_VERIFY=1
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT" || exit 1
+
+[[ -d one.ie/web && -d api && -d sync && -d channels && -d pay/backend ]] || {
+  echo "deploy.sh: not the one-ie monorepo (missing a service dir): $ROOT" >&2
+  exit 2
+}
+
+MODE="full"
+SKIP_TESTS=0 SKIP_TYPECHECK=0 SKIP_BUILD=0 SKIP_MIGRATIONS=0 SKIP_HEALTH=0
+ASSUME_YES="${DEPLOY_YES:-0}" DRY=0 ALLOW_DIRTY=0 ONLY_CHANGED=0 GATES_ONLY=0 CHECK_CREDS=0
+# A RED suite whose every failure is the shared TypeDB Cloud cluster refusing to
+# answer is waivable — nothing was disproven. Classified by signature, never by
+# filename, by typedb-flake-check.sh, which refuses the tasks:claim not_found
+# privilege boundary outright. --no-typedb-flake-waiver restores the hard stop.
+TYPEDB_FLAKE_WAIVER="${DEPLOY_ALLOW_TYPEDB_FLAKE:-1}" TESTS_WAIVED=0
+
+for a in "$@"; do
+  case "$a" in
+    dev|full|astro|workers|gateway|sync|agents|channels|pay) MODE="$a" ;;
+    --skip-tests) SKIP_TESTS=1 ;;
+    --skip-typecheck) SKIP_TYPECHECK=1 ;;
+    --skip-build) SKIP_BUILD=1 ;;
+    --skip-migrations) SKIP_MIGRATIONS=1 ;;
+    --skip-health) SKIP_HEALTH=1 ;;
+    --allow-dirty) ALLOW_DIRTY=1 ;;
+    --no-typedb-flake-waiver) TYPEDB_FLAKE_WAIVER=0 ;;
+    --changed) ONLY_CHANGED=1 ;;
+    --gates-only) GATES_ONLY=1 ;;
+    --check-creds) CHECK_CREDS=1 ;;
+    --all) ONLY_CHANGED=0 ;;
+    -y|--yes) ASSUME_YES=1 ;;
+    -n|--dry-run) DRY=1 ;;
+    -h|--help) sed -n '2,46p' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) echo "deploy.sh: unknown argument '$a' (try --help)" >&2; exit 2 ;;
+  esac
+done
+[[ "$MODE" == channels ]] && MODE=agents
+
+# ── dev tier ─────────────────────────────────────────────────────────────────
+# `./deploy dev` is a different destination with a different gate, so it exits
+# here rather than threading a flag through 700 lines of production pipeline.
+# deploy-dev.sh owns the dev procedure; this is only the door to it.
+if [[ "$MODE" == dev ]]; then
+  # --skip-tests is the only production flag that carries over: it is the dev
+  # script's DEV_SKIP_GATE. `(( SKIP_TESTS ))` and not `${SKIP_TESTS:+...}` —
+  # the latter expands on the literal string "0" and would silently skip the
+  # gate on every dev deploy.
+  dev_gate=0; (( SKIP_TESTS )) && dev_gate=1
+  if (( DRY )); then
+    echo "[dry] DEV_SKIP_GATE=$dev_gate bash .claude/scripts/deploy-dev.sh"
+    exit 0
+  fi
+  exec env "DEV_SKIP_GATE=$dev_gate" bash "$ROOT/.claude/scripts/deploy-dev.sh"
+fi
+
+LOG_DIR="$ROOT/.deploy-logs"
+mkdir -p "$LOG_DIR"
+STAMP="$(date +%Y%m%d-%H%M%S)"
+LOG="$LOG_DIR/deploy-$STAMP.log"
+
+RED=$'\033[31m'; GRN=$'\033[32m'; YEL=$'\033[33m'; DIM=$'\033[2m'; OFF=$'\033[0m'
+[[ -t 1 ]] || { RED=""; GRN=""; YEL=""; DIM=""; OFF=""; }
+
+say()  { printf '%s\n' "$*" | tee -a "$LOG"; }
+step() { printf '\n%s══ %s%s\n' "$DIM" "$*" "$OFF" | tee -a "$LOG"; }
+ok()   { printf '%s  ✓%s %s\n' "$GRN" "$OFF" "$*" | tee -a "$LOG"; }
+bad()  { printf '%s  ✗%s %s\n' "$RED" "$OFF" "$*" | tee -a "$LOG"; }
+warn() { printf '%s  !%s %s\n' "$YEL" "$OFF" "$*" | tee -a "$LOG"; }
+die()  { bad "$*"; say ""; say "log: $LOG"; exit 1; }
+
+# run <label> <dir> <cmd...> — logs, honours --dry-run, returns the exit code
+run() {
+  local label="$1" dir="$2"; shift 2
+  if (( DRY )); then say "  [dry] (cd $dir && $*)"; return 0; fi
+  say "  → $label"
+  ( cd "$ROOT/$dir" && unset CLOUDFLARE_API_TOKEN && "$@" ) >>"$LOG" 2>&1
+}
+
+want_astro=0 want_gateway=0 want_sync=0 want_agents=0 want_pay=0
+case "$MODE" in
+  full)    want_astro=1 want_gateway=1 want_sync=1 want_agents=1 want_pay=1 ;;
+  astro)   want_astro=1 ;;
+  workers) want_gateway=1 want_sync=1 want_agents=1 ;;
+  gateway) want_gateway=1 ;;
+  sync)    want_sync=1 ;;
+  agents)  want_agents=1 ;;
+  pay)     want_pay=1 ;;
+esac
+
+# --changed: a service whose tree has no new commits since its last successful
+# deploy has nothing to ship. The marker is written per service AFTER a clean
+# deploy, so an interrupted run never marks anything shipped. Secrets/bindings
+# change outside git — use --all (the default) when that's what you changed.
+svc_paths() { case "$1" in
+  astro)    echo "one.ie/web packages" ;;
+  gateway)  echo "api" ;;
+  sync)     echo "sync" ;;
+  channels) echo "channels packages" ;;
+  pay)      echo "pay/backend" ;;
+esac }
+mark_file() { echo "$LOG_DIR/last-$1.sha"; }
+svc_changed() { # 0 = has new commits (or no marker yet)
+  local last; last="$(cat "$(mark_file "$1")" 2>/dev/null)"
+  [[ -n "$last" ]] || return 0
+  git merge-base --is-ancestor "$last" HEAD 2>/dev/null || return 0
+  [[ -n "$(git log --oneline "$last..HEAD" -- $(svc_paths "$1") 2>/dev/null)" ]]
+}
+SKIPPED_UNCHANGED=()
+if (( ONLY_CHANGED )); then
+  for svc in astro gateway sync channels pay; do
+    case "$svc" in
+      astro)    (( want_astro ))   || continue ;;
+      gateway)  (( want_gateway )) || continue ;;
+      sync)     (( want_sync ))    || continue ;;
+      channels) (( want_agents ))  || continue ;;
+      pay)      (( want_pay ))     || continue ;;
+    esac
+    svc_changed "$svc" && continue
+    SKIPPED_UNCHANGED+=("$svc")
+    case "$svc" in
+      astro) want_astro=0 ;; gateway) want_gateway=0 ;; sync) want_sync=0 ;;
+      channels) want_agents=0 ;; pay) want_pay=0 ;;
+    esac
+  done
+fi
+
+# Typecheck only what is being shipped — `./deploy gateway` has no business
+# spending 30s on one.ie/web. Full mode still covers all five.
+SERVICES_TYPECHECK=()
+(( want_astro ))   && SERVICES_TYPECHECK+=(one.ie/web)
+(( want_gateway )) && SERVICES_TYPECHECK+=(api)
+(( want_sync ))    && SERVICES_TYPECHECK+=(sync)
+(( want_agents ))  && SERVICES_TYPECHECK+=(channels)
+(( want_pay ))     && SERVICES_TYPECHECK+=(pay/backend)
+
+if (( ONLY_CHANGED )) && ! (( want_astro + want_gateway + want_sync + want_agents + want_pay )); then
+  echo "deploy: nothing changed since the last deploy of ${SKIPPED_UNCHANGED[*]} — use --all to ship anyway"
+  exit 0
+fi
+
+say "deploy · mode=$MODE · $(date '+%Y-%m-%d %H:%M:%S')"
+say "log: $LOG"
+
+# ── Cloudflare credential resolution ────────────────────────────────────────
+# WHY THIS IS A LADDER AND NOT A LOOKUP (measured 2026-08-19, cost one red
+# deploy and one wrong diagnosis):
+#
+# There were THREE credentials reachable from one `./deploy`, and nothing chose
+# between them — each of the five services silently got whichever one its own
+# cwd happened to surface:
+#
+#   1. a STALE 37-char global key in the ambient env (injected by
+#      ~/.claude/settings.json `env`, so it exists in Claude Code sessions and
+#      NOT in a plain terminal — which is why it was invisible for so long).
+#      /user → 403. Dead.
+#   2. the GOOD 52-char key in one.ie/web/.env + .env.local. /user → 200.
+#      wrangler 4.x auto-loads `.env` from the CWD, so this one is only
+#      reachable from one.ie/web — the single directory of the five that has it.
+#   3. the `wrangler login` OAuth session, used when neither of the above is in
+#      scope.
+#
+# Process env BEATS a per-directory `.env`. So the stale key shadowed the good
+# one everywhere, Step 4's whoami probe failed, its `unset` cleared the ambient
+# key, and then: Step 6.5 in one.ie/web picked up (2) from `.env` and passed,
+# while Step 6.6 in channels — which has no `.env` — fell through to (3) and
+# died `code: 7403`. A deploy must never be able to use two different
+# credentials in two consecutive steps.
+#
+# The rules that follow from that:
+#   · RESOLVE one credential explicitly, from an ordered ladder of sources.
+#   · Test it with curl against the API — ground truth — never `wrangler
+#     whoami` in one directory, which answers about a credential the other four
+#     services will not use.
+#   · EXPORT the winner so all five run() subshells share it; that also
+#     neutralises the per-dir `.env` divergence without editing any `.env`.
+#   · NAME the source in the log (sha8 + length, never bytes).
+#   · PROVE all five services agree on the account id before shipping.
+#   · Run all of this BEFORE the 20-minute gates, not after them.
+CF_AUTH="" CF_AUTH_SOURCE="" CF_ACCOUNT=""
+
+# _cf_probe <email> <key> — 200 from /user means these exact bytes authenticate.
+# Ground truth, and direction-agnostic: it is equally able to prove a key ALIVE
+# (2026-08-19) as dead (2026-08-18). Never conclude either from wrangler alone.
+_cf_probe() {
+  local e="$1" k="$2" code
+  [[ -n "$e" && -n "$k" ]] || return 1
+  code="$(curl -s -m 15 -o /dev/null -w '%{http_code}' \
+            -H "X-Auth-Email: $e" -H "X-Auth-Key: $k" \
+            https://api.cloudflare.com/client/v4/user 2>/dev/null)"
+  [[ "$code" == "200" ]]
+}
+
+# _cf_fingerprint <secret> — length + sha8. The whole point of logging the
+# credential's identity is to make "which key was that?" answerable next time,
+# so it must be logged in a form that can never leak the key itself.
+_cf_fingerprint() { printf 'len=%s sha=%s' "${#1}" "$(printf %s "$1" | shasum | cut -c1-8)"; }
+
+# _cf_read <file> <var> — one value out of a .env-style file, quotes stripped.
+_cf_read() {
+  [[ -f "$1" ]] || return 1
+  local v; v="$(grep -m1 "^$2=" "$1" 2>/dev/null | cut -d= -f2- | tr -d '"'"'"'\r' | xargs)"
+  [[ -n "$v" ]] && printf '%s' "$v"
+}
+
+_cf_resolve() {
+  local e k src
+  # Rung 1-3: a global key from ambient env, then repo root, then one.ie/web.
+  # Ordered so an operator's explicit export still wins, but a STALE export
+  # cannot block a good key on disk — it just fails its probe and falls through.
+  for src in "ambient env" "$ROOT/.env.local" "$ROOT/one.ie/web/.env"; do
+    case "$src" in
+      "ambient env")
+        e="${CLOUDFLARE_EMAIL:-}"
+        k="${CLOUDFLARE_API_KEY:-${CLOUDFLARE_GLOBAL_API_KEY:-}}" ;;
+      *)
+        e="$(_cf_read "$src" CLOUDFLARE_EMAIL || true)"
+        k="$(_cf_read "$src" CLOUDFLARE_API_KEY || _cf_read "$src" CLOUDFLARE_GLOBAL_API_KEY || true)"
+        [[ -n "${e:-}" ]] || e="${CLOUDFLARE_EMAIL:-}" ;;
+    esac
+    if _cf_probe "${e:-}" "${k:-}"; then
+      # wrangler reads CLOUDFLARE_API_KEY; older copies of this script exported
+      # only CLOUDFLARE_GLOBAL_API_KEY, a name wrangler ignores (the 2026-08-18
+      # bug). Export BOTH so neither spelling can diverge again.
+      export CLOUDFLARE_EMAIL="$e" CLOUDFLARE_API_KEY="$k" CLOUDFLARE_GLOBAL_API_KEY="$k"
+      CF_AUTH="global-api-key"
+      CF_AUTH_SOURCE="$src ($(_cf_fingerprint "$k"))"
+      return 0
+    fi
+    [[ -n "${k:-}" ]] && say "    ${DIM}rejected: $src ($(_cf_fingerprint "$k")) — /user did not answer 200${OFF}"
+  done
+  # Rung 4: OAuth. Last, because it expires (~1h) and because a shadowing key
+  # must never let the deploy land here by accident. A DEAD ambient key would
+  # otherwise sit in the env poisoning every service, so strip all three now.
+  unset CLOUDFLARE_EMAIL CLOUDFLARE_API_KEY CLOUDFLARE_GLOBAL_API_KEY
+  if ( cd "$ROOT/one.ie/web" && ./node_modules/.bin/wrangler whoami >/dev/null 2>&1 ); then
+    CF_AUTH="oauth"; CF_AUTH_SOURCE="wrangler login session (expires ~1h — re-run 'wrangler login' if a step 403s)"
+    return 0
+  fi
+  return 1
+}
+
+# _cf_agree — every service must be deploying to the SAME account. This is the
+# check that would have caught 6.5-vs-6.6 before either ran: one.ie/web
+# answering about a different credential than channels IS the bug, and it is
+# only visible by asking each directory separately.
+_cf_agree() {
+  (( DRY )) && return 0
+  local d id first="" bad=0
+  for d in one.ie/web api sync channels pay/backend; do
+    id="$( cd "$ROOT/$d" 2>/dev/null && bunx wrangler whoami 2>/dev/null \
+           | grep -oE '[0-9a-f]{32}' | head -1 )"
+    if [[ -z "$id" ]]; then warn "$d — no account id from wrangler whoami"; bad=1; continue; fi
+    if [[ -z "$first" ]]; then first="$id"; CF_ACCOUNT="$id"
+    elif [[ "$id" != "$first" ]]; then
+      bad "$d resolves account $id, but one.ie/web resolves $first"
+      say "    a per-directory .env is overriding the resolved credential in $d"
+      bad=1
+    fi
+  done
+  (( bad )) && return 1
+  ok "5/5 services agree on account ${first:0:8}…"
+  return 0
+}
+
+# --check-creds — the red half. A gate that has never been seen to FAIL is not
+# known to work (repo canon: presence greps are not proof). This plants a key
+# that cannot authenticate and asserts the ladder REJECTS it and falls through,
+# then asserts the five services agree. Ships nothing.
+if (( CHECK_CREDS )); then
+  step "credential ladder — self-test"
+  fails=0
+  unset CLOUDFLARE_API_TOKEN
+  # Resolve for real first — tests 3 and 4 assert properties OF a resolution,
+  # so running them against an unresolved shell tests nothing.
+  _cf_resolve || die "self-test cannot run: no working credential on any rung"
+  ok "resolved: $CF_AUTH"
+
+  say "  1/4 · a dead key must be rejected, not exported"
+  if _cf_probe "nobody@example.invalid" "0000000000000000000000000000000000000"; then
+    bad "_cf_probe returned 0 for a key that cannot authenticate — the probe is fail-open"; fails=1
+  else ok "dead key rejected by /user probe"; fi
+
+  say "  2/4 · a live credential must still resolve with a dead key shadowing it"
+  ( export CLOUDFLARE_API_KEY="0000000000000000000000000000000000000" \
+           CLOUDFLARE_GLOBAL_API_KEY="0000000000000000000000000000000000000" \
+           CLOUDFLARE_EMAIL="nobody@example.invalid"
+    _cf_resolve >/dev/null 2>&1 && [[ -n "$CF_AUTH" ]] ) \
+    && ok "ladder fell through the shadowing key to a working rung" \
+    || { bad "a dead ambient key BLOCKS resolution — this is the 2026-08-19 bug"; fails=1; }
+
+  say "  3/4 · the resolved source must be named, and must not be the key itself"
+  if [[ "$CF_AUTH_SOURCE" == *"sha="* || "$CF_AUTH" == "oauth" ]]; then
+    ok "source reported: $CF_AUTH_SOURCE"
+  else bad "credential source is unnamed — the next confusion is unavoidable"; fails=1; fi
+  if [[ -n "${CLOUDFLARE_API_KEY:-}" && "$CF_AUTH_SOURCE" == *"${CLOUDFLARE_API_KEY}"* ]]; then
+    bad "the log line contains the key BYTES"; fails=1
+  else ok "no key bytes in the log line"; fi
+
+  say "  4/4 · all five services must agree on the account"
+  _cf_agree || fails=1
+
+  say ""
+  (( fails )) && die "credential self-test FAILED"
+  ok "credential self-test passed"
+  say "log: $LOG"; exit 0
+fi
+
+# ── Step 0.4 — credentials (BEFORE the slow gates) ──────────────────────────
+# It was after them: on 2026-08-18 a bad credential was discovered only at Step
+# 6.5, having already spent the full test suite and a 2m14s production build.
+# One curl costs nothing. Fail here.
+step "Step 0.4 — credentials"
+unset CLOUDFLARE_API_TOKEN
+_cf_resolve || die "no working Cloudflare credential — run 'wrangler login', or put a VALID CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL in .env.local"
+ok "resolved: $CF_AUTH"
+say "    source: $CF_AUTH_SOURCE"
+
+# ── Step 0 — tree state (before the slow gates: a dirty tree should fail fast)
+step "Step 0 — tree"
+# Same reasoning as the dirty-tree check, applied to the APPROVAL gate. That
+# prompt lives at Step 6, AFTER the gate battery, so a launch that can never
+# answer it pays for every typecheck, the whole suite and the astro build and
+# only then dies at `aborted at approval`. Measured 2026-09-04: one nohup'd
+# deploy burned a 189s green cycle exactly that way, and the box was contended
+# enough at the time that the preceding cycle had cost 5508s.
+#
+# stdin not a TTY means nobody can type "yes". Refuse here, where it is free.
+if (( ! ASSUME_YES )) && (( ! DRY )) && [[ "$(git rev-parse --abbrev-ref HEAD)" == "main" ]] && [[ ! -t 0 ]]; then
+  die "non-interactive (stdin is not a TTY) and the Step 6 approval prompt cannot be answered. Pass --yes / -y, or set DEPLOY_YES=1."
+fi
+BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+HEAD_SHA="$(git rev-parse --short HEAD)"
+say "  branch=$BRANCH head=$HEAD_SHA"
+DIRTY="$(git status --porcelain | wc -l | tr -d ' ')"
+if [[ "$DIRTY" != "0" ]]; then
+  git status --porcelain | sed 's/^/    /' | tee -a "$LOG"
+  if (( ALLOW_DIRTY )); then
+    warn "$DIRTY uncommitted path(s) — shipping anyway (--allow-dirty)"
+  else
+    die "$DIRTY uncommitted path(s). Commit them (deploy.sh does not write git history), or pass --allow-dirty."
+  fi
+else
+  ok "clean tree"
+fi
+
+# ── Steps 1+3 — the slow gates, all at once ─────────────────────────────────
+# typecheck ×5, vitest and the astro build share no STATE — the only thing they
+# share is the SDK's dist/, built first if missing. Running them concurrently
+# makes W0+build cost max() instead of sum(). Nothing here has a side effect
+# outside the working tree, so a red gate still stops the deploy before
+# anything ships.
+#
+# They are NOT independent in COST, and the comment here used to claim they
+# were. This box has 10 cores / 4 performance cores; the block above spawns 5
+# tsc, an 8 GiB-heap astro build, and a vitest that forks its own worker pool.
+# Anything inside the suite that shells out to a heavy child competes with all
+# of it — measured 2026-08-08, tests/integration/reconcile.test.ts (which runs
+# a full-repo tsc of its own) went 53s standalone → 376s here and blew its
+# budget, failing the PASSING direction and blocking a deploy over nothing.
+# Test budgets in this repo must therefore be sized for a STARVED run, not a
+# quiet one. If a gate ever needs the box to itself, take it out of this block
+# rather than widening every timeout downstream.
+
+# web + channels resolve @oneie/sdk types out of packages/sdk/dist — an unbuilt
+# dist fakes a wall of TS2307, so this one is a real dependency, done serially.
+if ! (( SKIP_TYPECHECK )) && [[ ! -d packages/sdk/dist ]]; then
+  step "Step 1.0 — @oneie/sdk build (dist/ missing)"
+  run "build @oneie/sdk" packages/sdk bun run build || die "SDK build failed — see $LOG"
+  ok "sdk built"
+fi
+
+# ── heavy-gate concurrency, priced in MEMORY not cores ──────────────────────
+# The five typechecks are cheap (~1s each, tree-fingerprint cached). The other
+# two are not: the astro build runs with --max-old-space-size=8192 and vitest
+# runs a driver plus 4 forks (~6GB). Both at once wants ~14GB, and this box has
+# 24GB with editors and sessions already resident.
+#
+# Cores were never the binding constraint, so price the gates in memory. What
+# this DOES buy: two gates that want ~14GB no longer overlap on a 24GB box.
+#
+# What it does NOT buy, and an earlier version of this comment wrongly claimed:
+# it is not the fix for the vitest gate HANGING. That was reproduced with the
+# gates serialised, the box at 41% free, no swap thrash and no sockets held —
+# see .claude/commands/deploy.md "The vitest gate hangs". Serialising addresses
+# a slow gate; the bound below is what addresses a parked one.
+#
+# Same reasoning as lib/govern.sh gate_headroom, but priced for THESE two gates
+# rather than a generic ~2GB cycle. A probe that cannot read memory returns a
+# large number — a broken sensor must never silently serialise the pipeline.
+HEAVY_NEED_GB="${DEPLOY_HEAVY_NEED_GB:-14}"   # build 8 + vitest ~6
+# shellcheck source=lib/govern.sh
+. "$ROOT/.claude/scripts/lib/govern.sh"
+# This used to be `hw.memsize * memory_pressure "free percentage" / 100`, which
+# is the defect lib/govern.sh documents at length: that percentage counts file
+# cache, purgeable and compressed pages as free. Measured 2026-09-03 it read 74%
+# on a box with 1.3% actually free and 9.4 GB in swap — so this gate overlapped
+# two ~7 GB gates on a machine that had ~3 GB. gate_mem_avail_mb is the honest
+# quantity. Unreadable probe still returns 999: a broken sensor must never
+# silently serialise the pipeline.
+heavy_free_gb() {
+  local avail_mb
+  avail_mb="$(gate_mem_avail_mb 2>/dev/null || echo "")"
+  [ -z "$avail_mb" ] && { echo 999; return 0; }
+  echo $(( avail_mb / 1024 ))
+}
+HEAVY_FREE_GB="$(heavy_free_gb)"
+if (( HEAVY_FREE_GB >= HEAVY_NEED_GB )); then HEAVY_PARALLEL=1; else HEAVY_PARALLEL=0; fi
+[[ "${DEPLOY_HEAVY_PARALLEL:-}" == 1 ]] && HEAVY_PARALLEL=1   # escape hatch
+
+if (( HEAVY_PARALLEL )); then
+  step "Steps 1+3 — gates in parallel (typecheck ×5 · vitest · astro build)"
+  say "  memory: ${HEAVY_FREE_GB}GB free >= ${HEAVY_NEED_GB}GB needed — heavy gates overlap"
+else
+  step "Steps 1+3 — gates (typecheck ×5 parallel · vitest + astro build serial)"
+  say "  memory: ${HEAVY_FREE_GB}GB free < ${HEAVY_NEED_GB}GB needed — heavy gates serialised"
+  say "          (overlapping them pages; measured 1145s vs 176s — see deploy.sh)"
+fi
+
+GATE_NAMES=() GATE_PIDS=() GATE_LOGS=() GATE_RC=() GATE_T=() GATE_DUR=()
+GATE_BOUND="${DEPLOY_GATE_TIMEOUT:-900}"   # healthy vitest 176s, build 174s
+# Typechecks were run bare on the claim that they are "cached ~1s each". They
+# are NOT: no tsconfig in this repo sets `incremental`/`tsBuildInfoFile`, so
+# every one is a full check. Measured 2026-08-23: a single one held 1.5GB for
+# 12m, and five run in parallel — ~7.5GB of fan-out that the HEAVY_NEED_GB test
+# below never covered, because it prices only vitest+build. On a cold worktree
+# that is the whole melt (load 52, swap 20GB).
+#
+# So price them the same way: if the box cannot hold the fan-out, route them
+# through the semaphore. deploy.sh holds no slot itself, so the nested calls
+# really do queue (gate-run.sh is re-entrant — this would be cosmetic if an
+# outer slot were held). A warm, healthy box still runs them bare and parallel.
+TSC_EACH_GB="${DEPLOY_TSC_EACH_GB:-2}"
+TSC_NEED_GB=$(( TSC_EACH_GB * ${#SERVICES_TYPECHECK[@]} ))
+if (( HEAVY_FREE_GB >= TSC_NEED_GB )); then TSC_GOVERNED=0; else TSC_GOVERNED=1; fi
+[[ "${DEPLOY_TSC_GOVERNED:-}" == 1 ]] && TSC_GOVERNED=1   # escape hatch
+[[ "${DEPLOY_TSC_GOVERNED:-}" == 0 ]] && TSC_GOVERNED=0
+gate_start() { # <name> <dir> <cmd...>
+  local name="$1" dir="$2"; shift 2
+  if (( DRY )); then say "  [dry] (cd $dir && $*)"; return; fi
+  local out="$LOG_DIR/$name-$STAMP.log"
+  ( cd "$ROOT/$dir" && unset CLOUDFLARE_API_TOKEN && "$@" ) >"$out" 2>&1 &
+  GATE_NAMES+=("$name"); GATE_PIDS+=("$!"); GATE_LOGS+=("$out"); GATE_RC+=(-1)
+  GATE_T+=("$SECONDS"); GATE_DUR+=(-1)
+  say "  → $name (pid $!)"
+}
+# Heavy gates run under gate-run.sh for its BOUND and its process-group REAP:
+# macOS ships no timeout(1), and killing only the shell reparents the vitest
+# forks to launchd. A hung gate must die on a clock, not outlive the deploy.
+gate_start_governed() { # <name> <dir> <cmd...>
+  local name="$1" dir="$2"; shift 2
+  if (( DRY )); then say "  [dry] (cd $dir && gate-run.sh deploy-$name -- $*)"; return; fi
+  local out="$LOG_DIR/$name-$STAMP.log"
+  ( cd "$ROOT/$dir" && unset CLOUDFLARE_API_TOKEN \
+      && GOVERN_GATE_TIMEOUT="$GATE_BOUND" \
+         exec "$ROOT/.claude/scripts/gate-run.sh" "deploy-$name" -- "$@" ) >"$out" 2>&1 &
+  GATE_NAMES+=("$name"); GATE_PIDS+=("$!"); GATE_LOGS+=("$out"); GATE_RC+=(-1)
+  GATE_T+=("$SECONDS"); GATE_DUR+=(-1)
+  say "  → $name (pid $!, bound ${GATE_BOUND}s)"
+}
+# gate_start_heavy — same, but when memory says the two heavy gates cannot
+# overlap, block until the previous heavy gate has finished. Its exit status is
+# recorded in GATE_RC so the collection loop below never waits on a reaped pid
+# (a second `wait` on the same child returns 127 and would read as a failure).
+HEAVY_IDX=()
+gate_start_heavy() {
+  if (( ! DRY )) && (( ! HEAVY_PARALLEL )) && (( ${#HEAVY_IDX[@]} )); then
+    local prev="${HEAVY_IDX[${#HEAVY_IDX[@]}-1]}"
+    say "  … waiting for ${GATE_NAMES[$prev]} before starting $1 (serialised)"
+    if wait "${GATE_PIDS[$prev]}"; then GATE_RC[$prev]=0; else GATE_RC[$prev]=1; fi
+    GATE_DUR[$prev]=$(( SECONDS - GATE_T[$prev] ))
+  fi
+  gate_start_governed "$@"
+  (( DRY )) || HEAVY_IDX+=( $(( ${#GATE_NAMES[@]} - 1 )) )
+}
+
+GATE_T0=$SECONDS
+if ! (( SKIP_TYPECHECK )); then
+  if (( TSC_GOVERNED )); then
+    say "  memory: ${HEAVY_FREE_GB}GB free < ${TSC_NEED_GB}GB needed — typechecks governed (queued)"
+  else
+    say "  memory: ${HEAVY_FREE_GB}GB free >= ${TSC_NEED_GB}GB needed — typechecks bare (parallel)"
+  fi
+  # NOT routed through tsc-cached.sh, and that is a measurement, not an oversight.
+  # Measured 2026-09-01 on a warm box: one.ie/web 4s · api 0s · sync 0s ·
+  # channels 2s · pay/backend 2s -- 8s serial, ~4s of wall-clock in parallel, and
+  # they finish inside the vitest gate's shadow anyway, so caching them buys zero
+  # seconds off the deploy. It would also COST something: tsc-cached takes the
+  # per-folder `tsc-<folder>` gate_lock that do-reconcile.sh takes, so a /do cycle
+  # typechecking one.ie/web would make this gate queue up to TSC_CACHE_WAIT (900s)
+  # and then exit 1 -- a red ship gate caused by lock contention rather than by
+  # code. Four seconds is not worth that trade.
+  for svc in "${SERVICES_TYPECHECK[@]}"; do
+    if (( TSC_GOVERNED )); then
+      gate_start_governed "tsc-$(echo "$svc" | tr / -)" "$svc" bunx tsc --noEmit
+    else
+      gate_start "tsc-$(echo "$svc" | tr / -)" "$svc" bunx tsc --noEmit
+    fi
+  done
+fi
+# the suite lives in one.ie/web and gates that worker
+# The vitest gate hangs when stdout is not a TTY (fork spawned, never given
+# work — see deploy.md). `script -qeF` allocates a pty and flushes so the
+# runner matches a green standalone terminal; `--reporter=dot` is the other
+# half of that unstick (default reporter still hung under script).
+# test-cached.sh keys a PASS on the exact inputs -- args + selected test files +
+# `git diff HEAD` by CONTENT + untracked contents + HEAD. deploy refuses a dirty
+# tree, so on the normal path the key collapses to (args, HEAD, test-file set):
+# a full suite already proven green at this exact commit is not run twice. Only
+# passes are memoised, so a red suite re-runs every time until it is green.
+#
+# TEST_CACHE_PTY=1 is not optional here: this gate's stdout is a log file, and the
+# runner hangs on a non-TTY stdout (a fork is spawned and never given work). The
+# wrapper is the same `script -qeF /dev/null` that fixed it, moved inside the memo
+# so the cached and uncached paths run byte-identical commands.
+# The vitest ARGS used to live here, spelled out. They now live in test-full.sh,
+# which /close reaches too -- test-cached keys on argv, so two spellings of the
+# same suite could never share a stamp and a warm tree paid it twice.
+(( SKIP_TESTS || ! want_astro )) || gate_start_heavy vitest one.ie/web \
+  env TEST_CACHE_PTY=1 bash "$ROOT/.claude/scripts/test-full.sh"
+if (( want_astro )); then
+  if (( SKIP_BUILD )); then
+    [[ -d one.ie/web/dist/server ]] || die "--skip-build but one.ie/web/dist/server/ does not exist"
+  else
+    gate_start_heavy build one.ie/web bash "$ROOT/.claude/scripts/astro-build-cached.sh"
+  fi
+fi
+
+TYPECHECK_REPORT="skipped" TESTS_REPORT="skipped" BUILD_REPORT="skipped"
+tc_pass=0 tc_total=0 gate_fail=()
+for i in $(seq 0 $(( ${#GATE_NAMES[@]} - 1 )) ); do
+  (( ${#GATE_NAMES[@]} )) || break
+  name="${GATE_NAMES[$i]}" glog="${GATE_LOGS[$i]}"
+  if (( ${GATE_RC[$i]} >= 0 )); then rc="${GATE_RC[$i]}"      # already reaped when serialised
+  elif wait "${GATE_PIDS[$i]}"; then rc=0; else rc=1; fi
+  GATE_RC[$i]=$rc   # record it: the deploy receipt below reads results, not just timings
+  (( ${GATE_DUR[$i]} < 0 )) && GATE_DUR[$i]=$(( SECONDS - GATE_T[$i] ))
+  cat "$glog" >>"$LOG"
+  case "$name" in
+    tsc-*)
+      tc_total=$((tc_total+1))
+      if (( rc )); then bad "${name#tsc-} typecheck FAILED"; gate_fail+=("$name")
+      else tc_pass=$((tc_pass+1)); fi ;;
+    vitest)
+      # The suite now runs as TWO lanes, so the log carries TWO "Tests N passed"
+      # lines and `tail -1` reported only the last one — the 19-file typedb lane.
+      # A deploy that ran 10940 tests said "143 passed", which understates the
+      # gate by two orders of magnitude and reads like a partial run. Sum them.
+      TESTS_REPORT="$(awk '
+        /Tests +[0-9]+ (passed|failed)/ {
+          for (i = 1; i <= NF; i++) {
+            if ($i == "passed") p += $(i-1) + 0
+            if ($i == "failed") f += $(i-1) + 0
+          }
+          n++
+        }
+        # vitest reports UNHANDLED errors on their own line — "Errors  45 errors" —
+        # and exits non-zero on them with ZERO failed tests. A verdict that reads
+        # only the Tests line printed "11327 passed" for a red run and the flake
+        # checker called it GREEN (measured 2026-09-05). Read the Errors line too.
+        /Errors +[0-9]+ errors?/ { for (i = 1; i <= NF; i++) if ($i ~ /^errors?$/) e += $(i-1) + 0 }
+        END {
+          if (n == 0) exit
+          if (n > 1) printf "Tests %d passed", p; else printf "Tests %d passed", p
+          if (f > 0) printf " | %d failed", f
+          if (e > 0) printf " | %d unhandled errors", e
+          if (n > 1) printf " (%d lanes)", n
+          printf "\n"
+        }' "$glog")"
+      if (( rc )); then
+        bad "${TESTS_REPORT:-vitest failed}"
+        say "  Failing files (check the Known-Flaky allowlist in .claude/commands/deploy.md):"
+        grep -E '^ *(FAIL|❯ .*\.test\.ts.*(failed|×))' "$glog" | sort -u | sed 's/^/    /' | tee -a "$LOG"
+        # Is the whole red run just the shared substrate being down? The checker
+        # answers by SIGNATURE, and blocks on the first failure it cannot account
+        # for — so a real break standing beside a 503 still stops the deploy.
+        _flake_out=""
+        if (( TYPEDB_FLAKE_WAIVER )); then
+          _flake_out="$(bash "$ROOT/.claude/scripts/typedb-flake-check.sh" "$glog" 2>&1)"; _flake_rc=$?
+        else
+          _flake_out="typedb-flake: waiver disabled (--no-typedb-flake-waiver)"; _flake_rc=1
+        fi
+        printf '%s\n' "$_flake_out" | sed 's/^/    /' | tee -a "$LOG"
+        if (( _flake_rc == 0 )); then
+          TESTS_WAIVED=1
+          TESTS_REPORT="${TESTS_REPORT:-vitest failed} — WAIVED as TypeDB outage (suite NOT green)"
+          ok "test failures waived: shared TypeDB Cloud unavailable"
+        else
+          gate_fail+=(vitest)
+        fi
+      elif grep -q 'cache HIT' "$glog"; then
+        # Say WHICH it was. A reused pass and a fresh run are both green, but
+        # reporting a memo hit as "all pass" is the same class of dishonesty as
+        # reporting a fast lane as a full one -- the operator cannot tell whether
+        # 10,780 tests just executed or whether an earlier identical tree's
+        # result was replayed. Both are sound; only one of them took 20 minutes.
+        TESTS_REPORT="full suite REUSED — identical inputs already passed ($(grep -o 'already PASSED.*' "$glog" | tail -1))"
+        ok "$TESTS_REPORT"
+      else
+        TESTS_REPORT="${TESTS_REPORT:-all pass}"; ok "$TESTS_REPORT"
+      fi ;;
+    build)
+      if (( rc )); then bad "astro build FAILED"; gate_fail+=(build)
+      else BUILD_REPORT="ok"; ok "astro build clean"; fi ;;
+  esac
+done
+(( tc_total )) && {
+  TYPECHECK_REPORT="$tc_pass/$tc_total services clean"
+  (( tc_pass == tc_total )) && ok "$TYPECHECK_REPORT"
+}
+if (( ${#GATE_NAMES[@]} )); then
+  GATE_WALL="$((SECONDS - GATE_T0))s"
+  # Per-gate, not just the aggregate. The gates overlap, so the total is max()
+  # over the parallel set and sum() over the serialised heavies -- without the
+  # breakdown there is no way to tell which one is actually the critical path,
+  # and "make the deploy faster" turns into caching whatever finishes inside
+  # vitest's shadow for zero seconds.
+  for i in $(seq 0 $(( ${#GATE_NAMES[@]} - 1 )) ); do
+    say "    ${GATE_NAMES[$i]}: ${GATE_DUR[$i]}s"
+  done
+  say "  gates wall-clock: $GATE_WALL"
+  [[ "$BUILD_REPORT" == ok ]] && BUILD_REPORT="$GATE_WALL (overlapped)"
+fi
+(( ${#gate_fail[@]} )) && die "gates red: ${gate_fail[*]} — nothing deployed"
+
+# ── deferred-pin debt ───────────────────────────────────────────────────────
+# verify-fast.sh may DEFER its pinned integration suites mid-plan and record the
+# debt in a machine-keyed ledger. That debt is meant to come due at the close
+# gate. deploy is the LAST place it can come due, and until now it could not:
+# deploy sets FULL_VERIFY=1 but invokes vitest directly, so it never reached the
+# branch in verify-fast.sh that settles the ledger. A production deploy could
+# therefore ship over pins that no run had ever executed.
+#
+# Two rules, both one-directional:
+#   · a GREEN full suite PAYS the debt. The suite is a superset of every pin, so
+#     reaching here green is the payment -- same reasoning verify-fast uses.
+#   · anything else REFUSES. A skipped suite does not pay a debt; neither does a
+#     red one (we never get here) nor a `--gates-only` run that skipped tests.
+#     An unpaid debt with no run to settle it is an unrun gate, and an unrun gate
+#     is not a passing gate.
+DEBT_FILE="${VERIFY_FAST_DEBT_FILE:-${TMPDIR:-/tmp}/one-verify-fast-debt}"
+if [[ -s "$DEBT_FILE" ]]; then
+  step "Deferred-pin debt"
+  say "  ledger: $DEBT_FILE"
+  sed 's/^/    /' "$DEBT_FILE" | tee -a "$LOG"
+  if (( SKIP_TESTS )) || [[ "$TESTS_REPORT" == "skipped" ]]; then
+    die "deferred pins are outstanding and this run did not execute the suite — re-run without --skip-tests"
+  fi
+  # A waived run is not a green run. The debt exists precisely because the pinned
+  # gates were deferred, and a waiver says only that the failures we DID see were
+  # substrate — it says nothing about a pin that never got to report.
+  if (( TESTS_WAIVED )); then
+    die "deferred pins are outstanding and the suite was WAIVED, not green — re-run when TypeDB answers"
+  fi
+  rm -f "$DEBT_FILE"
+  ok "debt settled by the green full suite"
+fi
+if (( GATES_ONLY )); then
+  say ""; ok "gates green in ${GATE_WALL:-0s} — nothing shipped (--gates-only)"
+  say "  Typecheck:  $TYPECHECK_REPORT"; say "  Tests:      $TESTS_REPORT"; say "  Log: $LOG"
+  exit 0
+fi
+
+# ── Step 4 — credentials (the real work happens in Step 0.4) ────────────────
+step "Step 4 — credentials"
+ok "auth verified ($CF_AUTH) · API_TOKEN unset"
+say "    source: $CF_AUTH_SOURCE"
+_cf_agree || die "services disagree about which Cloudflare account they are deploying to"
+
+# ── Step 5 — smoke ──────────────────────────────────────────────────────────
+step "Step 5 — smoke"
+for cfg in api/wrangler.toml sync/wrangler.toml channels/wrangler.toml \
+           one.ie/web/wrangler.toml pay/backend/wrangler.toml; do
+  [[ -f "$cfg" ]] || die "missing wrangler config: $cfg"
+done
+ok "5/5 wrangler configs present"
+if (( want_astro )); then
+  [[ -d one.ie/web/dist/server ]] || die "one.ie/web/dist/server/ missing after build"
+  GZIP_HINT="$(grep -Eo 'gzip: *[0-9.]+ *[KM]iB' "$LOG" | tail -1)"
+  say "  dist/server: $(du -sh one.ie/web/dist/server | cut -f1)"
+fi
+# --env is the decoy trap; assert no config reintroduced an env-scoped target
+if grep -q '^\[env\.production' one.ie/web/wrangler.toml 2>/dev/null; then
+  warn "one.ie/web/wrangler.toml grew an [env.production] block — the deploy-target trap is reachable again"
+fi
+
+# ── Step 6 — approval ───────────────────────────────────────────────────────
+step "Step 6 — approval"
+TARGETS=()
+(( want_gateway )) && TARGETS+=("api → one-gateway")
+(( want_sync ))    && TARGETS+=("sync → one-sync (cron-only)")
+(( want_agents ))  && TARGETS+=("channels → channels.one.ie")
+(( want_pay ))     && TARGETS+=("pay/backend → one-core-worker")
+(( want_astro ))   && TARGETS+=("one.ie/web → one-prod (one.ie)")
+for t in "${TARGETS[@]}"; do say "    $t"; done
+if (( ASSUME_YES || DRY )); then
+  ok "auto-approved"
+elif [[ "$BRANCH" != "main" ]]; then
+  ok "auto-approved (branch $BRANCH ≠ main)"
+else
+  read -r -p "  deploy to production? [yes/N] " reply
+  [[ "$reply" == "yes" ]] || die "aborted at approval"
+fi
+
+# ── Step 6.5 — D1 migrations ────────────────────────────────────────────────
+MIG_REPORT="skipped"
+if (( want_astro )) && ! (( SKIP_MIGRATIONS )); then
+  step "Step 6.5 — D1 migrations (DB, remote)"
+  if run "d1 migrations apply DB --remote" one.ie/web bunx wrangler d1 migrations apply DB --remote; then
+    if (( DRY )); then
+      MIG_REPORT="dry-run"
+    elif tail -40 "$LOG" | grep -q "No migrations to apply"; then
+      MIG_REPORT="none to apply"
+    else
+      MIG_REPORT="$(grep -Eo '[0-9]{4}_[a-z0-9_]+\.sql' "$LOG" | tail -5 | tr '\n' ' ')"
+      MIG_REPORT="applied: ${MIG_REPORT:-see log}"
+    fi
+    ok "$MIG_REPORT"
+  else
+    die "D1 migrations failed — never ship worker code ahead of its schema"
+  fi
+fi
+
+# ── Step 6.6 — D1 migrations (channels) ─────────────────────────────────────
+# A SECOND database. The step above runs in one.ie/web, where `DB` is
+# `one-owners`; channels binds `DB` to `claw` and keeps its own
+# channels/migrations/. Nothing applied that directory: the step above never
+# enters it, and channels' own `bun run migrate` was pinned to 0001_init.sql.
+# So 0010_action_bindings.sql shipped with the C6 worker code and its table was
+# never created — and because bindAction's INSERT was fire-and-forget, every
+# button binding failed silently, leaving taps that resolve to nothing. The
+# promise's accept (`ls channels/migrations/*action*.sql`) proved the FILE
+# existed, never the table. Same rule as above: schema before code.
+MIG_CHAN_REPORT="skipped"
+if (( want_agents )) && ! (( SKIP_MIGRATIONS )); then
+  step "Step 6.6 — D1 migrations (channels DB, remote)"
+  if run "d1 migrations apply DB --remote (channels)" channels bunx wrangler d1 migrations apply DB --remote; then
+    if (( DRY )); then
+      MIG_CHAN_REPORT="dry-run"
+    elif tail -40 "$LOG" | grep -q "No migrations to apply"; then
+      MIG_CHAN_REPORT="none to apply"
+    else
+      MIG_CHAN_REPORT="$(grep -Eo '[0-9]{4}_[a-z0-9_]+\.sql' "$LOG" | tail -5 | tr '\n' ' ')"
+      MIG_CHAN_REPORT="applied: ${MIG_CHAN_REPORT:-see log}"
+    fi
+    ok "$MIG_CHAN_REPORT"
+  else
+    die "channels D1 migrations failed — never ship worker code ahead of its schema"
+  fi
+fi
+
+# ── Step 7 — deploy ─────────────────────────────────────────────────────────
+step "Step 7 — deploy"
+# bash 3.2 on macOS has no associative arrays — two parallel indexed ones
+BG_NAMES=() BG_PIDS=()
+hfail=()
+deploy_bg() { # <name> <dir> <cmd...>
+  local name="$1" dir="$2"; shift 2
+  if (( DRY )); then say "  [dry] (cd $dir && ${*})"; return; fi
+  local out="$LOG_DIR/$name-$STAMP.log"
+  ( cd "$ROOT/$dir" && unset CLOUDFLARE_API_TOKEN && "$@" ) >"$out" 2>&1 &
+  BG_NAMES+=("$name"); BG_PIDS+=("$!")
+  say "  → $name (pid $!, log $out)"
+}
+
+# All five upload independently — no shared state, no ordering constraint
+# (verified 2026-07-08 for the three workers; astro's only dependency is its own
+# build, already done). Astro is slowest (~30s), so it starts first.
+# NEVER --env production on any of them — it ships to the one-prod-production decoy.
+(( want_astro ))   && deploy_bg astro    one.ie/web   bunx wrangler deploy
+(( want_gateway )) && deploy_bg gateway  api          bunx wrangler deploy
+(( want_sync ))    && deploy_bg sync     sync         bunx wrangler deploy
+(( want_agents ))  && deploy_bg channels channels     bunx wrangler deploy
+(( want_pay ))     && deploy_bg pay      pay/backend  bun run deploy
+
+DEPLOY_FAIL=()
+for i in $(seq 0 $(( ${#BG_NAMES[@]} - 1 )) ); do
+  (( ${#BG_NAMES[@]} )) || break
+  name="${BG_NAMES[$i]}"
+  if wait "${BG_PIDS[$i]}"; then
+    ok "$name deployed"
+    cat "$LOG_DIR/$name-$STAMP.log" >>"$LOG"
+  else
+    bad "$name FAILED"
+    tail -30 "$LOG_DIR/$name-$STAMP.log" | sed 's/^/    /' | tee -a "$LOG"
+    DEPLOY_FAIL+=("$name")
+  fi
+done
+(( ${#DEPLOY_FAIL[@]} )) && die "parallel deploy failed: ${DEPLOY_FAIL[*]}"
+if ! (( DRY )); then
+  for i in $(seq 0 $(( ${#BG_NAMES[@]} - 1 )) ); do
+    (( ${#BG_NAMES[@]} )) || break
+    git rev-parse HEAD > "$(mark_file "${BG_NAMES[$i]}")"
+  done
+fi
+(( want_astro && ! DRY )) && GZIP_HINT="$(grep -Eo 'gzip: *[0-9.]+ *[KM]iB' "$LOG_DIR/astro-$STAMP.log" | tail -1)"
+
+# ── Step 8 — health ─────────────────────────────────────────────────────────
+HEALTH_REPORT="skipped"
+if (( SKIP_HEALTH || DRY )); then
+  step "Step 8 — health (skipped)"
+else
+  step "Step 8 — health (custom domains only)"
+  probe() { # <label> <url> <assert-substring|-> ; 3 tries, backoff
+    local label="$1" url="$2" want="$3" i body code
+    for i in 1 2 3; do
+      body="$(curl -sL --max-time 20 -w $'\n%{http_code}' "${url}?_t=$(date +%s)" 2>/dev/null)"
+      code="${body##*$'\n'}"; body="${body%$'\n'*}"
+      if [[ "$code" == "200" ]] && { [[ "$want" == "-" ]] || [[ "$body" == *"$want"* ]]; }; then
+        ok "$label 200"; return 0
+      fi
+      sleep $((i * 3))
+    done
+    bad "$label unhealthy (last code=${code:-none})"
+    return 1
+  }
+  # probe all four at once — they are independent hosts; serial cost was the
+  # sum of four round trips plus, on a bad deploy, three backoff sleeps each
+  hp=0 ht=0 PNAMES=() PPIDS=()
+  probe_bg() { probe "$2" "$3" "$4" >"$LOG_DIR/health-$1-$STAMP.log" 2>&1 & PNAMES+=("$1"); PPIDS+=("$!"); ht=$((ht+1)); }
+  (( want_gateway )) && probe_bg gateway  "api.one.ie/health"  https://api.one.ie/health      -
+  (( want_astro ))   && probe_bg astro    "one.ie/api/health"  https://one.ie/api/health      '"status":"ok"'
+  (( want_agents ))  && probe_bg channels "channels.one.ie"    https://channels.one.ie/health -
+  (( want_pay ))     && probe_bg pay      "pay.one.ie/status"  https://pay.one.ie/status      '"ok"'
+  for i in $(seq 0 $(( ${#PNAMES[@]} - 1 )) ); do
+    (( ${#PNAMES[@]} )) || break
+    if wait "${PPIDS[$i]}"; then hp=$((hp+1)); else hfail+=("${PNAMES[$i]}"); fi
+    cat "$LOG_DIR/health-${PNAMES[$i]}-$STAMP.log" | tee -a "$LOG"
+  done
+  (( want_sync )) && ok "sync — cron-only, deploy success IS the health signal"
+  HEALTH_REPORT="$hp/$ht HTTP 200"
+  (( want_sync )) && HEALTH_REPORT="$HEALTH_REPORT + sync deploy-confirmed"
+
+  # ── deploy receipt ────────────────────────────────────────────────────────
+  # The last deploy's gate timings and per-worker outcome, read by the operator
+  # deploy dashboard at /u/one/deploy. Written HERE because health is the last
+  # fact it needs. Three honesty rules the data itself forces:
+  #
+  #   * gates in this file are only ever GREEN — `die "gates red"` above exits
+  #     long before Step 8, so a red gate never reaches a receipt. The page says
+  #     that out loud rather than letting "all pass" imply a full audit.
+  #   * `healthy` is null for sync. It is never probed (cron-only — the line two
+  #     above), and a worker nobody asked must not render healthy OR unhealthy.
+  #   * `deployed` comes from BG_NAMES — what actually uploaded — never from
+  #     TARGETS, which is only the intent.
+  #
+  # Wrapped in `{ … } || true` so a failed write can never fail a deploy that
+  # has already shipped.
+  _receipt="$ROOT/one.ie/web/src/lib/generated/deploy-receipt.json"
+  {
+    mkdir -p "$(dirname "$_receipt")"
+    {
+      printf '{\n  "stamp": "%s",\n  "headSha": "%s",\n  "mode": "%s",\n' \
+        "$STAMP" "${HEAD_SHA:-unknown}" "$MODE"
+      printf '  "gates": ['
+      _sep=""
+      for i in $(seq 0 $(( ${#GATE_NAMES[@]} - 1 )) ); do
+        (( ${#GATE_NAMES[@]} )) || break
+        if   (( ${GATE_RC[$i]} <  0 )); then _res=unrun
+        elif (( ${GATE_RC[$i]} >  0 )); then _res=fail
+        else                                 _res=pass; fi
+        printf '%s\n    {"name": "%s", "seconds": %s, "result": "%s"}' \
+          "$_sep" "${GATE_NAMES[$i]}" "${GATE_DUR[$i]}" "$_res"
+        _sep=","
+      done
+      (( ${#GATE_NAMES[@]} )) && printf '\n  '
+      printf '],\n  "workers": ['
+      _sep=""
+      for i in $(seq 0 $(( ${#BG_NAMES[@]} - 1 )) ); do
+        (( ${#BG_NAMES[@]} )) || break
+        _n="${BG_NAMES[$i]}"
+        if   [[ "$_n" == sync ]];              then _h=null    # never probed
+        # `${hfail[*]-}` not `${hfail[*]}`: under `set -u` bash 3.2 treats an EMPTY
+        # array as unbound, and hfail is empty exactly when every probe passed —
+        # so a perfect deploy died here (line 933, 2026-09-05), truncated its own
+        # receipt mid-JSON and reported exit 1. Same trap test-lanes.sh already paid.
+        elif [[ " ${hfail[*]-} " == *" $_n "* ]]; then _h=false
+        else                                        _h=true; fi
+        printf '%s\n    {"name": "%s", "deployed": true, "healthy": %s}' "$_sep" "$_n" "$_h"
+        _sep=","
+      done
+      (( ${#BG_NAMES[@]} )) && printf '\n  '
+      printf ']\n}\n'
+    } >"$_receipt" && say "  receipt: $_receipt"
+  } || true
+fi
+
+# ── Report ──────────────────────────────────────────────────────────────────
+step "Step 9 — speed (advisory)"
+# Post-deploy Lighthouse reading of the LIVE site. ADVISORY: it reports, it
+# does not block a deploy that already shipped. The ENFORCED ratchet runs
+# pre-deploy against the local production build (`bun run speed` in one.ie/web),
+# because live-site numbers swing ~30 points on network jitter and cannot gate.
+#
+# Placed here, serial and after the parallel deploys, deliberately: Lighthouse
+# drives a full Chrome and would fight the Step 1+3 gate fan-out and the machine
+# governor's slot cap if it ran alongside them.
+#
+# Exit 2 = INCONCLUSIVE (could not measure). It is reported as such and NEVER
+# as a pass — an unrun check is not a green check.
+if (( DRY )); then
+  echo "  (dry run — speed check skipped)" | tee -a "$LOG"
+elif [[ "${SKIP_SPEED:-0}" == "1" ]]; then
+  echo "  (SKIP_SPEED=1 — skipped)" | tee -a "$LOG"
+else
+  sp_out="$LOG_DIR/speed-$STAMP.log"
+  sp_cmd=(node "$(dirname "${BASH_SOURCE[0]}")/speed-check.mjs" --prod --runs 3)
+  # The verdict, from the exit code. One function, used by both the inline and
+  # the detached path, so the two can never phrase the same code differently.
+  # NOTE: bad() only PRINTS in this script (die() is what exits). That is
+  # correct here — Step 9 runs AFTER the deploy has shipped, so failing the
+  # pipeline could not un-ship it. This step reports; it does not block. The
+  # blocking gate is `bun run speed` pre-deploy against the local build.
+  # warn() is used so a red x is never mistaken for a blocked deploy.
+  speed_verdict() {
+    grep -E 'perf=|faster|SLOWER|performance:|advisory only' "$sp_out" | sed 's/^/    /' | tee -a "$LOG" || true
+    case "$1" in
+      0) ok   "speed: nothing got slower (live site)" ;;
+      1) warn "speed: REGRESSION on the live site — ADVISORY, deploy not blocked — $sp_out" ;;
+      2) warn "speed: INCONCLUSIVE (not a pass) — ADVISORY — $sp_out" ;;
+      # 3 = regressions found, deliberately not gating (--prod). Distinct from 0
+      # so it can never render as "nothing got slower" — which it did, twice, in
+      # the same log that printed the regression two lines above.
+      3) warn "speed: REGRESSION on the live site — advisory, not gating — $sp_out" ;;
+      # 124 is run_bounded's own code: Lighthouse hung past the cap and was
+      # reaped. Reported as unrun, never as a pass.
+      124) warn "speed: TIMED OUT (not a pass) — ADVISORY — $sp_out" ;;
+      *) warn "speed: unexpected exit $1 — ADVISORY — $sp_out" ;;
+    esac
+  }
+  if [[ "${SPEED_SYNC:-0}" == "1" ]]; then
+    # Inline — the operator wants the number before leaving the terminal.
+    run_bounded "${SPEED_TIMEOUT:-600}" "${sp_cmd[@]}" >"$sp_out" 2>&1
+    speed_verdict $?
+  else
+    # DETACHED, by default. Measured 2026-09-05 on deploy-20260904-173517: the
+    # pipeline was 227s wall-clock, and 166s of it was THIS step — three
+    # Lighthouse runs over six routes against a site that had already shipped
+    # and already passed health at +61s. The number is advisory by design, so
+    # nothing downstream waits on it; the only thing that waited was the
+    # operator. The verdict is appended to $LOG when it lands, in the same
+    # words the inline path uses, and the process is bounded so a hung Chrome
+    # cannot outlive the deploy by more than SPEED_TIMEOUT.
+    (
+      run_bounded "${SPEED_TIMEOUT:-600}" "${sp_cmd[@]}" >"$sp_out" 2>&1
+      rc=$?
+      { echo ""; echo "══ Step 9 — speed (detached, landed $(date -u +%FT%TZ))"; } >>"$LOG"
+      speed_verdict $rc >>"$LOG" 2>&1
+    ) >/dev/null 2>&1 </dev/null &
+    disown 2>/dev/null || true
+    say "  speed: measuring the live site in the background (pid $!, ~3 min)"
+    say "         verdict lands in $LOG · raw: $sp_out · inline: SPEED_SYNC=1"
+  fi
+fi
+
+step "Report"
+say "  Mode:       $MODE"
+say "  Branch:     $BRANCH @ $HEAD_SHA"
+say "  Typecheck:  $TYPECHECK_REPORT"
+say "  Tests:      $TESTS_REPORT"
+say "  Build:      $BUILD_REPORT"
+say "  Migrations: $MIG_REPORT"
+say "  Deployed:   ${TARGETS[*]:-none}"
+say "  Health:     $HEALTH_REPORT"
+[[ -n "${sp_out:-}" && "${SPEED_SYNC:-0}" != "1" ]] && say "  Speed:      detached — $sp_out"
+(( ${#SKIPPED_UNCHANGED[@]} )) && say "  Unchanged:  ${SKIPPED_UNCHANGED[*]} (skipped, --changed)"
+[[ -n "${GZIP_HINT:-}" ]] && say "  Bundle:     $GZIP_HINT"
+say "  Log:        $LOG"
+
+if (( ${#hfail[@]} )); then
+  say ""
+  bad "degraded — unhealthy: ${hfail[*]}"
+  say "  rollback: cd one.ie/web && bunx wrangler rollback --name one-prod"
+  exit 1
+fi
+say ""
+ok "deploy:success"