@oneie/claude 0.9.0 → 0.10.0

package/scripts/deploy.sh

@@ -38,18 +38,14 @@
 #   · 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
+#   · a fast pass is NEVER reported as a full pass, and `dev` never touches prod
+#   · dev.one.ie shares PRODUCTION's D1 and KV — ship dev freely, treat its DATA
+#     as production                                    incident:deploy-two-tiers
 #
-# 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.
+# ACCOUNTS — why each gate is shaped the way it is (dates, shas, what it cost):
+#   bash .claude/scripts/incident.sh --for .claude/scripts/deploy.sh
+# What a gate MEANS: .claude/commands/deploy.md · its traps:
+#   .claude/skills/deploy/REFERENCE.md
 
 set -uo pipefail
 
@@ -69,10 +65,8 @@ cd "$ROOT" || exit 1
 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.
+# A red suite that is only the shared TypeDB cluster refusing to answer is
+# waivable — classified by SIGNATURE, never by filename.  incident:waived-pass-is-a-fact
 TYPEDB_FLAKE_WAIVER="${DEPLOY_ALLOW_TYPEDB_FLAKE:-1}" TESTS_WAIVED=0
 
 for a in "$@"; do
@@ -98,14 +92,11 @@ 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.
+# A different destination with a different gate is a different procedure.
+# deploy-dev.sh owns it; this is only the door.          incident:deploy-two-tiers
 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.
+  # `(( SKIP_TESTS ))`, never `${SKIP_TESTS:+...}` — the latter expands on the
+  # literal "0" and skips the gate every time.          incident:deploy-two-tiers
   dev_gate=0; (( SKIP_TESTS )) && dev_gate=1
   if (( DRY )); then
     echo "[dry] DEV_SKIP_GATE=$dev_gate bash .claude/scripts/deploy-dev.sh"
@@ -148,10 +139,8 @@ case "$MODE" in
   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.
+# --changed skips a service with no new commits since its last CLEAN deploy.
+# Secrets and bindings change outside git — use --all.        incident:changed-marker
 svc_paths() { case "$1" in
   astro)    echo "one.ie/web packages" ;;
   gateway)  echo "api" ;;
@@ -203,40 +192,11 @@ 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.
+# A LADDER, not a lookup. Resolve ONE credential from an ordered list, prove it
+# with curl against the API (never `wrangler whoami`, which answers about one
+# directory), EXPORT the winner so all five subshells share it, name the source
+# as sha8+length (never bytes), and prove all five agree on the account id —
+# all of it BEFORE the 20-minute gates.          incident:cf-credential-ladder
 CF_AUTH="" CF_AUTH_SOURCE="" CF_ACCOUNT=""
 
 # _cf_probe <email> <key> — 200 from /user means these exact bytes authenticate.
@@ -300,10 +260,8 @@ _cf_resolve() {
   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 — every service must deploy to the SAME account, and that is only
+# visible by asking each directory separately.   incident:cf-credential-ladder
 _cf_agree() {
   (( DRY )) && return 0
   local d id first="" bad=0
@@ -323,10 +281,8 @@ _cf_agree() {
   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.
+# --check-creds — the RED half: a gate never seen to fail is not known to work.
+# Plants a key that cannot authenticate.           incident:check-creds-red-half
 if (( CHECK_CREDS )); then
   step "credential ladder — self-test"
   fails=0
@@ -366,6 +322,59 @@ if (( CHECK_CREDS )); then
   say "log: $LOG"; exit 0
 fi
 
+# ── Step 0.1 — the box (BEFORE everything, because everything below is a gate) ──
+# Same reasoning as Step 0.4 one step further back: the cheapest check runs
+# first. health.sh --box costs ~0.2s and owns every number in it (this reads,
+# never restates). The verdict vocabulary is HEALTHY | DEGRADED | UNHEALTHY, and
+# its own --self-test proves each threshold bites.
+#
+# WHY A PAGING BOX IS A DEPLOY CONCERN. A deploy runs five heavy gates. On a box
+# under swap pressure each one runs long, and a slow gate is indistinguishable
+# from a red one at the wall clock — measured 2026-09-05, an 8-fork vitest run
+# showed a >20-minute wall clock that was governor QUEUEING, not runtime. A good
+# tree then gets diagnosed as broken code, which is the most expensive wrong
+# answer this script can give.
+#
+# DEGRADED never refuses: it means headroom of one gate, or orphans that survived
+# a reap, and one gate is what a deploy needs. Only UNHEALTHY stops, and it names
+# the agent that can fix it rather than telling you to wait.
+step "Step 0.1 — box"
+if [ "${DEPLOY_SKIP_DOCTOR:-0}" = "1" ]; then
+  say "  skipped (DEPLOY_SKIP_DOCTOR=1)"
+elif [ ! -x "$ROOT/.claude/scripts/health.sh" ] && [ ! -f "$ROOT/.claude/scripts/health.sh" ]; then
+  say "  health.sh absent — box unmeasured (never read this as healthy)"
+else
+  _box_json="$( bash "$ROOT/.claude/scripts/health.sh" --box --json 2>/dev/null )"
+  _box_v="$(printf '%s' "$_box_json" | sed -n 's/.*"verdict":"\([A-Z]*\)".*/\1/p')"
+  _box_why="$(printf '%s' "$_box_json" | sed -n 's/.*"why":"\([^"]*\)".*/\1/p')"
+  _box_orph="$(printf '%s' "$_box_json" | sed -n 's/.*"orphans":\([0-9]*\).*/\1/p')"
+  case "${_box_v:-unknown}" in
+    HEALTHY)  ok "box HEALTHY" ;;
+    DEGRADED) say "  box DEGRADED — ${_box_why:-?} (proceeding: a deploy needs one gate)" ;;
+    UNHEALTHY)
+      # Reap first, but only when there is something to reap: with orphans=0 the
+      # verdict is about memory or headroom and no reaper can move it. Running one
+      # anyway is the ritual that makes a refusal look like it tried something.
+      if [ "${_box_orph:-0}" != "0" ]; then
+        bash "$ROOT/.claude/scripts/gate-reaper.sh" --once 2>/dev/null | sed 's/^/  /'
+        _box_json="$( bash "$ROOT/.claude/scripts/health.sh" --box --json 2>/dev/null )"
+        _box_v="$(printf '%s' "$_box_json" | sed -n 's/.*"verdict":"\([A-Z]*\)".*/\1/p')"
+        _box_why="$(printf '%s' "$_box_json" | sed -n 's/.*"why":"\([^"]*\)".*/\1/p')"
+        say "  box after reap: ${_box_v:-unknown}"
+      fi
+      if [ "${_box_v:-unknown}" = "UNHEALTHY" ] && (( ! DRY )); then
+        say "  ${_box_why:-the box is saturated}"
+        say "  Hand the box to the doctor, then deploy:"
+        say "    Agent({ subagent_type: \"doctor\", model: \"opus\","
+        say "            prompt: \"health.sh says: ${_box_why:-saturated}. Reclaim what nothing is coming back for, then report.\" })"
+        say "  Override (the gates will be slow, not wrong):  DEPLOY_SKIP_DOCTOR=1 ./deploy"
+        die "box is UNHEALTHY — refusing to start five gates on it"
+      fi
+      say "  box UNHEALTHY — ${_box_why:-?} (dry run: reporting, refusing nothing)" ;;
+    *) say "  box verdict unreadable — unmeasured, which is never a pass" ;;
+  esac
+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.
@@ -378,14 +387,8 @@ 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.
+# stdin not a TTY means nobody can type "yes" at Step 6. Refuse here, where it
+# is free, not after the whole gate battery.        incident:approval-needs-a-tty
 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
@@ -405,28 +408,35 @@ else
 fi
 
 # ── Step 0.5 — generated artifacts (cheap, before the slow gates) ─────────
-# Same reasoning as Step 0.4: one cheap deterministic check, run where failing is
-# free, rather than after five typechecks, the whole suite and an astro build.
-#
-# blocks-manifest.mjs builds THREE COMMITTED artifacts from one block registry --
-# one.ie/web/src/lib/puck/block-manifest.json (what tooling reads),
-# channels/src/generated/block-enum.ts (what the model is told) and
-# one.ie/web/src/lib/puck/block-schema.generated.ts (what the browser normalises
-# against) -- and until 2026-09-09 nothing ran it: not this script, not
-# verify-fast.sh, not a test. `grep -c blocks-manifest` on both was 0 and 0.
-# A drifted enum ships a vocabulary the model is told about and the browser
-# cannot render, so the generator belongs on the SHIP gate and not only the
-# dev lane.
-#
-# Step 0 has already refused a dirty tree, so what --check diffs is exactly what
-# would ship. It exits non-zero on drift AND on failing to run, and both stop the
-# deploy: an unrun gate is not a pass.
+# One cheap deterministic check, run where failing is free. It exits non-zero on
+# drift AND on failing to run, and both stop the deploy.
 #
-# THE DRY BRANCH IS EXPLICIT, and it has to be: `run` returns 0 under --dry-run
-# (see its definition above), so `if run ...; then ok "no drift"` would print a
-# GREEN verdict for a check that never executed -- an unrun gate reported as a
-# pass, in the one script where that is the cardinal sin. `gate_start` below
-# already handles DRY the same way: say what would run, record no verdict.
+# THE DRY BRANCH IS EXPLICIT: `run` returns 0 under --dry-run, so
+# `if run ...; then ok` would print GREEN for a check that never executed — an
+# unrun gate reported as a pass.                    incident:blocks-manifest-unrun
+# ── Step 0.5a — deps present (0.05s, and it buys ~290s) ─────────────────────
+# Every service this run will typecheck must have a node_modules. A missing one
+# does not read as missing: tsc reports `TS2688: Cannot find type definition file
+# for '@cloudflare/workers-types'` — a TypeScript error naming TypeScript — and
+# it surfaces at the END of the gate fan-out, ~290s in, on code that is fine.
+# Measured 2026-09-17 at the ship gate: api and sync red in all four worktrees at
+# once, because worktree-up.sh's LINKS list carried neither. That list is fixed;
+# this check is the half that cannot rot, because it holds for a tree materialised
+# any other way.
+step "Step 0.5a — deps"
+_deps_missing=()
+for _svc in "${SERVICES_TYPECHECK[@]}"; do
+  [ -e "$ROOT/$_svc/node_modules" ] || _deps_missing+=("$_svc")
+done
+if (( ${#_deps_missing[@]} )); then
+  for _svc in "${_deps_missing[@]}"; do say "  ✗ $_svc/node_modules missing"; done
+  say "  A worktree is not \`git worktree add\` — that command omits every gitignored path."
+  say "  Link them: bash .claude/scripts/worktree-up.sh <name> --no-dev"
+  say "  Or by hand: ln -sfn <main-tree>/$'{'svc'}'/node_modules \$svc/node_modules"
+  die "${#_deps_missing[@]} service(s) cannot typecheck — refusing at t≈7s rather than t≈290s"
+fi
+ok "${#SERVICES_TYPECHECK[@]}/${#SERVICES_TYPECHECK[@]} services have deps"
+
 step "Step 0.5 — generated artifacts"
 if (( DRY )); then
   say "  [dry] node .claude/scripts/blocks-manifest.mjs --check"
@@ -438,22 +448,11 @@ else
 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.
+# They share no STATE (only the SDK's dist/, built first), so concurrency makes
+# W0+build cost max() instead of sum(). They are NOT independent in COST:
+# TEST BUDGETS HERE MUST BE SIZED FOR A STARVED RUN, not a quiet one, and a gate
+# that needs the box to itself leaves this block rather than widening every
+# timeout downstream.                        incident:gates-not-independent-in-cost
 
 # 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.
@@ -464,33 +463,15 @@ if ! (( SKIP_TYPECHECK )) && [[ ! -d packages/sdk/dist ]]; then
 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.
+# Cores were never the binding constraint. Serialising addresses a SLOW gate; it
+# is NOT the fix for the vitest gate hanging — the bound below is. A probe that
+# cannot read memory returns a large number: a broken sensor must never silently
+# serialise the pipeline.                incident:heavy-gates-priced-in-memory
 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.
+# gate_mem_avail_mb, never memory_pressure's "free percentage" — that counts
+# cache and compressed pages as free.     incident:heavy-gates-priced-in-memory
 heavy_free_gb() {
   local avail_mb
   avail_mb="$(gate_mem_avail_mb 2>/dev/null || echo "")"
@@ -511,44 +492,18 @@ else
 fi
 
 # ── the run, streamed into the world ────────────────────────────────────────
-# Until 2026-09-07 this script emitted NOTHING — no signal, no row — and a
-# committed JSON file was a deploy's only trace. `deploy-emit.sh` puts each gate
-# on the same run/event stream /do and the factory already write to, LIVE, so a
-# reader can see a deploy that is happening rather than only one that happened.
-#
-# THREE RULES, and all three are about not making the telemetry load-bearing:
-#
-#  1. IT CAN NEVER FAIL THE DEPLOY. Backgrounded and `|| true`, exactly as
-#     _record_run is guarded. A gate that passed while the network was down is
-#     still a gate that passed, and a deploy going red because it could not
-#     phone home is a worse failure than the one it was reporting.
-#  2. IT CAN NEVER SLOW THE DEPLOY. `&` — the emitter's own --max-time is 8s and
-#     that must not land on the critical path of a gate somebody is waiting on.
-#  3. --dry-run EMITS NOTHING. A run row for a deploy that did not happen is the
-#     theater /deploy already refuses to render. Checked here, because the
-#     emitter cannot know its caller's flags.
-#
-# A dropped emit degrades to a GAP in the trace, never to a lie: the mapper
-# treats an absent stage as absent and has no default frame.
-# bash 3.2 (what macOS ships) closes `$(` at the FIRST `)` it meets — and a
-# case pattern ends in one. So the old form,
-#   EMIT_TARGET="$( case "$MODE" in dev) echo dev.one.ie ;; *) echo one.ie ;; esac )"
-# raised `syntax error near unexpected token` at run time and left EMIT_TARGET
-# holding the literal tail ` echo dev.one.ie ;; *) echo one.ie ;; esac )`, which
-# was then passed as --target and written into deploy-runs.json. Measured on the
-# 2026-09-08 production ship, in the log, twice.
-#
-# That is the one outcome the comment above forbids: an emit that degrades to a
-# LIE rather than a gap. deploy-runs.json is the artifact the release path reads
-# to learn what production runs, so a false target there misinforms the next
-# person to ask "what is live". An `if` has no pattern and no closing paren.
+# THREE RULES, all about not making the telemetry load-bearing: it can never FAIL
+# the deploy (backgrounded, `|| true`) · it can never SLOW the deploy (`&`) ·
+# --dry-run emits NOTHING. A dropped emit degrades to a GAP in the trace, never
+# to a lie.                              incident:deploy-emit-never-load-bearing
+# An `if`, not `$( case ... esac )`: bash 3.2 closes `$(` at the FIRST `)`, and a
+# case pattern ends in one — it wrote a literal into deploy-runs.json, which is
+# the one degradation the rules above forbid.  incident:deploy-emit-never-load-bearing
 if [ "$MODE" = dev ]; then EMIT_TARGET="dev.one.ie"; else EMIT_TARGET="one.ie"; fi
 EMIT_ENV="$( [[ "$MODE" == dev ]] && echo dev || echo prod )"
 
-# deploy.sh's gate names are implementation names (`tsc-one.ie-web`, `vitest`);
-# DEPLOY_SPINE_STEPS are the pipeline's. Anything unmapped emits NOTHING rather
-# than inventing a stage — an unknown stage is refused at the receiver anyway,
-# and a gate the spine has no name for is better absent than mislabelled.
+# Anything unmapped emits NOTHING rather than inventing a stage — better absent
+# than mislabelled.                      incident:deploy-emit-never-load-bearing
 _spine_stage() {
   case "$1" in
     tsc-*)   echo typecheck ;;
@@ -558,10 +513,8 @@ _spine_stage() {
   esac
 }
 
-# The verdict CLOSES the run, and it is a field of its own rather than something
-# inferred from the last stage to arrive. `--gates-only` is a complete,
-# successful run that never reaches ship or health; closing on a stage would
-# leave every one of those runs `open` forever in every run list.
+# The verdict CLOSES the run, and is a field of its own — --gates-only is a
+# complete run that never reaches ship.  incident:deploy-verdict-closes-the-run
 _emit_verdict() {
   local v="$1"
   _emit --verdict "$v" \
@@ -575,11 +528,14 @@ _emit_verdict() {
   wait -n 2>/dev/null || true
 }
 
+# --slug is load-bearing: without it prod answers `forbidden` to every frame.
+#                                              incident:ask-slug-load-bearing
 _emit() {  # ...deploy-emit.sh args
   [[ -x "$ROOT/.claude/scripts/deploy-emit.sh" ]] || return 0
   (( DRY )) && return 0
   ( bash "$ROOT/.claude/scripts/deploy-emit.sh" \
       --run "$STAMP" --target "$EMIT_TARGET" --env "$EMIT_ENV" \
+      --slug "${DEPLOY_SLUG:-one}" \
       --door "deploy${MODE:+ $MODE}" \
       --sha "$(git -C "$ROOT" rev-parse --short HEAD 2>/dev/null || echo '')" \
       "$@" >/dev/null 2>&1 || true ) &
@@ -588,17 +544,10 @@ _emit() {  # ...deploy-emit.sh args
 
 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.
+# Typechecks are NOT "cached ~1s each" — no tsconfig sets `incremental`, so five
+# full checks fan out to ~7.5GB that HEAVY_NEED_GB never priced. If the box
+# cannot hold the fan-out, route them through the semaphore; a warm box runs them
+# bare and parallel.                            incident:tsc-not-cached-on-ship
 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
@@ -635,10 +584,9 @@ gate_start_governed() { # <name> <dir> <cmd...>
   { st="$(_spine_stage "$name")"; [[ -n "$st" ]] && _emit --stage "$st" --status start; } || true
   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).
+# gate_start_heavy — blocks until the previous heavy gate finished when memory
+# says they cannot overlap, and records its status in GATE_RC so the collection
+# loop never waits on a reaped pid.      incident:gate-start-heavy-wait-127
 HEAVY_IDX=()
 gate_start_heavy() {
   if (( ! DRY )) && (( ! HEAVY_PARALLEL )) && (( ${#HEAVY_IDX[@]} )); then
@@ -658,33 +606,14 @@ if ! (( SKIP_TYPECHECK )); then
   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.
-  # CONTENT TYPES FIRST, and this line is worth its four seconds.
-  #
-  # `astro check` and `astro build` sync implicitly; raw `tsc --noEmit` does NOT,
-  # and `DataEntryMap` is GENERATED into the gitignored one.ie/web/.astro/. So a
-  # freshly-materialised tree carries whatever that directory happened to hold —
-  # for .release/, types from before the newest collection existed; for a new
-  # worktree, no file at all. Either way tsc rejects the collection key and the
-  # gate goes red on code that is fine.
-  #
-  # Measured three times on 2026-09-06/07, each costing a full gate: twice on
-  # .release/ during a promote, once on a fresh worktree. The error names
-  # TypeScript and the cause is Astro, which is why it kept being re-diagnosed:
-  #   src/lib/docs/sections.ts(23,40): error TS2344:
-  #     Type '"docs"' does not satisfy the constraint 'keyof DataEntryMap'.
-  #
-  # It must run BEFORE the fan-out rather than inside the one.ie/web gate: the
-  # five typechecks start concurrently, and a sync racing them writes the types
-  # out from under a tsc that is already reading them.
+  # NOT routed through tsc-cached.sh, and that is a measurement: it would buy
+  # zero seconds and could turn a ship gate red on LOCK CONTENTION rather than on
+  # code.                                       incident:tsc-not-cached-on-ship
+  # CONTENT TYPES FIRST, and worth its four seconds. Raw `tsc --noEmit` does not
+  # sync, `DataEntryMap` is generated into the gitignored .astro/, and a TS2344
+  # on a collection key is an ASTRO fault wearing a TypeScript error. Must run
+  # BEFORE the fan-out, or a sync races the tscs already reading those types.
+  #                                     incident:astro-content-sync-before-tsc
   if (( want_astro )) && [[ -d one.ie/web ]]; then
     ( cd one.ie/web && NODE_OPTIONS=--max-old-space-size=4096 \
         ./node_modules/.bin/astro sync >/dev/null 2>&1 ) \
@@ -700,25 +629,75 @@ if ! (( SKIP_TYPECHECK )); then
   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.
+# The vitest gate hangs on a non-TTY stdout; `script -qeF` + `--reporter=dot` is
+# the unstick.                              incident:vitest-pty-and-memo-probe
+# TEST_CACHE_PTY=1 is not optional (this gate's stdout is a log file), the argv
+# lives in test-full.sh so /close and deploy share one stamp, and the memo is
+# PROBED BEFORE A SLOT IS TAKEN — a hit needs no memory, no forks and no slot.
+#                                           incident:vitest-pty-and-memo-probe
+#                                           incident:memo-hit-is-not-all-pass
 #
-# 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 TYPEDB_LANE_NONBLOCKING=1 TEST_CACHE_PTY=1 bash "$ROOT/.claude/scripts/test-full.sh"
+# >>> vitest-memo-probe (extracted VERBATIM by deploy-gate-check.sh — keep self-contained)
+# _memo_probe — "is EVERY lane already a green stamp for this exact tree?" Runs
+# nothing, computes nothing, writes nothing.
+#   0 = every lane HIT (stdout: one `already PASSED <ts>` line per lane)
+#   1 = at least one lane MISSES  ·  2 = cannot answer
+# Anything but 0 takes the slot and runs the gate: an unrun check is not a pass.
+# It asks per LANE, never `TEST_CACHE_PROBE=1 test-full.sh` — that would skip the
+# whole gate on a pool-only hit.            incident:vitest-pty-and-memo-probe
+_memo_probe() {
+  local cache="${TEST_CACHE_DIR:-${TMPDIR:-/tmp}/one-test-cache}"
+  [[ "${TEST_CACHE_DISABLE:-0}" == "1" ]] && return 2
+  local keys
+  keys="$( TEST_CACHE_KEY_ONLY=1 bash "$ROOT/.claude/scripts/test-full.sh" 2>/dev/null \
+           | grep -Eo '^[0-9a-f]{64}$' )"
+  [[ -n "$keys" ]] || return 2          # no key ⇒ no answer ⇒ run the gate
+  local k f hit n=0
+  while IFS= read -r k; do
+    [[ -n "$k" ]] || continue
+    n=$((n+1)); hit=""
+    for f in "$cache"/*"$k".pass; do
+      if [[ -f "$f" ]]; then hit="$f"; break; fi
+    done
+    [[ -n "$hit" ]] || return 1         # one miss is a miss: the gate runs
+    printf '    lane %s — identical inputs already PASSED %s\n' \
+           "${k:0:12}" "$(cat "$hit" 2>/dev/null)"
+  done <<< "$keys"
+  (( n )) || return 2
+  return 0
+}
+if (( SKIP_TESTS || ! want_astro )); then
+  :                                      # --skip-tests keeps its own meaning
+else
+  _mp_t0=$SECONDS
+  _mp_out="$(_memo_probe)"; _mp_rc=$?
+  _mp_dur=$(( SECONDS - _mp_t0 ))
+  if (( _mp_rc == 0 )) && (( DRY )); then
+    say "  [dry] vitest gate would be REUSED from the memo (no slot taken)"
+  elif (( _mp_rc == 0 )); then
+    # NOT via gate_start_heavy and not in HEAVY_IDX: a gate with no process is
+    # not a heavy gate, and `wait 0` on a non-child exits 127.
+    #                                      incident:gate-start-heavy-wait-127
+    _mp_log="$LOG_DIR/vitest-$STAMP.log"
+    { echo "[deploy] vitest gate SKIPPED by the memo probe — every lane of the full suite"
+      echo "[deploy] is already a green stamp for this exact tree. No governor slot taken."
+      printf '%s\n' "$_mp_out"
+      echo "[deploy] probe cost ${_mp_dur}s"
+    } > "$_mp_log"
+    GATE_NAMES+=(vitest); GATE_PIDS+=(0); GATE_LOGS+=("$_mp_log"); GATE_RC+=(0)
+    GATE_T+=("$SECONDS"); GATE_DUR+=("$_mp_dur")
+    { st="$(_spine_stage vitest)"; [[ -n "$st" ]] && _emit --stage "$st" --status start; } || true
+    say "  → vitest (memo HIT in ${_mp_dur}s — no slot taken)"
+  else
+    case "$_mp_rc" in
+      1) say "  memo probe: MISS — no green stamp for at least one lane of this tree" ;;
+      *) say "  memo probe: could not answer — running the gate (an unrun check is not a pass)" ;;
+    esac
+    gate_start_heavy vitest one.ie/web \
+      env TYPEDB_LANE_NONBLOCKING=1 TEST_CACHE_PTY=1 bash "$ROOT/.claude/scripts/test-full.sh"
+  fi
+fi
+# <<< vitest-memo-probe
 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"
@@ -736,10 +715,9 @@ for i in $(seq 0 $(( ${#GATE_NAMES[@]} - 1 )) ); do
   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] ))
-  # …and onto the stream. ONE hook for typecheck/tests/build — the three gates
-  # that are ~95% of the wall clock and carry the metrics deploy-runs.json has
-  # no shape for. Deferred to after the `case` below for `tests`, which is the
-  # only gate whose reused/waived facts are not known yet at this line.
+  # …and onto the stream. ONE hook for the three gates that are ~95% of the wall
+  # clock. Deferred past the `case` for `tests`, whose reused/waived facts are not
+  # known at this line.                   incident:deploy-emit-never-load-bearing
   _emit_stage="$(_spine_stage "$name")"
   _emit_dur=$(( GATE_DUR[i] < 0 ? 0 : GATE_DUR[i] ))
   cat "$glog" >>"$LOG"
@@ -749,10 +727,8 @@ for i in $(seq 0 $(( ${#GATE_NAMES[@]} - 1 )) ); do
       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.
+      # TWO lanes means TWO "Tests N passed" lines — SUM them; `tail -1` reported
+      # 143 for a 10940-test run.        incident:two-lanes-tail-1-understates
       TESTS_REPORT="$(awk '
         /Tests +[0-9]+ (passed|failed)/ {
           for (i = 1; i <= NF; i++) {
@@ -761,10 +737,8 @@ for i in $(seq 0 $(( ${#GATE_NAMES[@]} - 1 )) ); do
           }
           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.
+        # Read the Errors line too: vitest exits non-zero on UNHANDLED errors
+        # with ZERO failed tests.        incident:two-lanes-tail-1-understates
         /Errors +[0-9]+ errors?/ { for (i = 1; i <= NF; i++) if ($i ~ /^errors?$/) e += $(i-1) + 0 }
         END {
           if (n == 0) exit
@@ -795,12 +769,14 @@ for i in $(seq 0 $(( ${#GATE_NAMES[@]} - 1 )) ); do
         else
           gate_fail+=(vitest)
         fi
+      elif grep -q 'SKIPPED by the memo probe' "$glog"; then
+        # A reused pass is never reported as "all pass", and the stamp's own
+        # timestamp rides along.           incident:memo-hit-is-not-all-pass
+        TESTS_REPORT="full suite REUSED — identical inputs already passed (memo probe, no slot taken: $(grep -o 'already PASSED.*' "$glog" | tail -1))"
+        ok "$TESTS_REPORT"
       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.
+        # Say WHICH it was — both are sound, only one took 20 minutes.
+        #                                  incident:memo-hit-is-not-all-pass
         TESTS_REPORT="full suite REUSED — identical inputs already passed ($(grep -o 'already PASSED.*' "$glog" | tail -1))"
         ok "$TESTS_REPORT"
       else
@@ -810,14 +786,9 @@ for i in $(seq 0 $(( ${#GATE_NAMES[@]} - 1 )) ); do
       if (( rc )); then bad "astro build FAILED"; gate_fail+=(build)
       else BUILD_REPORT="ok"; ok "astro build clean"; fi ;;
   esac
-  # AFTER the case, deliberately: `tests` only learns whether it was a memo hit
-  # or a waived failure inside it, and those two booleans are the whole reason
-  # this stream exists. Emitting before the case would carry the timing and lose
-  # the meaning.
-  #
-  # `waived` is the one that matters most. On 2026-09-06 a flake waiver let this
-  # gate exit 0 on a genuinely red suite, and deploy-runs.json recorded `green`
-  # with nothing to distinguish it. A waived pass is now a fact on the run.
+  # AFTER the case: `tests` only learns reused/waived inside it, and those two
+  # booleans are the whole reason this stream exists. A waived pass is a FACT on
+  # the run.                                   incident:waived-pass-is-a-fact
   if [[ -n "$_emit_stage" ]]; then
     _emit_args=(--stage "$_emit_stage" --wall-ms "$(( _emit_dur * 1000 ))")
     if (( rc )) && ! { [[ "$_emit_stage" == tests ]] && (( TESTS_WAIVED )); }; then
@@ -843,11 +814,9 @@ done
 }
 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.
+  # Per-gate, not just the aggregate — without the breakdown "make the deploy
+  # faster" caches whatever finishes inside vitest's shadow for zero seconds.
+  #                                    incident:deploy-verdict-closes-the-run
   for i in $(seq 0 $(( ${#GATE_NAMES[@]} - 1 )) ); do
     say "    ${GATE_NAMES[$i]}: ${GATE_DUR[$i]}s"
   done
@@ -864,20 +833,10 @@ 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.
+# deploy is the LAST place verify-fast's deferred pins can come due. Two rules,
+# both one-directional: a GREEN full suite PAYS the debt (the suite is a superset
+# of every pin) · anything else REFUSES. An unpaid debt with no run to settle it
+# is an unrun gate.                                  incident:deferred-pin-debt
 DEBT_FILE="${VERIFY_FAST_DEBT_FILE:-${TMPDIR:-/tmp}/one-verify-fast-debt}"
 if [[ -s "$DEBT_FILE" ]]; then
   step "Deferred-pin debt"
@@ -898,11 +857,9 @@ 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"
-  # CLOSE THE RUN. This exit is the one --gates-only always takes, and it is the
-  # path this feature is exercised by most (every release.sh promote mints its
-  # receipt through it). Without this the run would carry its gate frames and
-  # sit `open` forever — the precise failure the verdict field was added to
-  # prevent, and it is only not a bug because of this line.
+  # CLOSE THE RUN — the --gates-only exit, which every release.sh promote takes.
+  # Without this line the run sits `open` for ever.
+  #                                    incident:deploy-verdict-closes-the-run
   _emit_verdict green
   exit 0
 fi
@@ -968,15 +925,9 @@ if (( want_astro )) && ! (( SKIP_MIGRATIONS )); then
 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.
+# A SECOND database: channels binds `DB` to `claw` and keeps its own migrations,
+# and nothing applied that directory. Same rule as 6.5: schema before code.
+#                                                incident:channels-second-d1
 MIG_CHAN_REPORT="skipped"
 if (( want_agents )) && ! (( SKIP_MIGRATIONS )); then
   step "Step 6.6 — D1 migrations (channels DB, remote)"
@@ -1078,20 +1029,11 @@ else
   (( 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.
+  # Three honesty rules the data itself forces: gates here are only ever GREEN (a
+  # red one died long before Step 8) · `healthy` is NULL for sync, which is never
+  # probed · `deployed` is BG_NAMES (what uploaded), never TARGETS (the intent).
+  # `|| true` so a failed write cannot fail a shipped deploy.
+  #                                        incident:deploy-receipt-honesty
   _receipt="$ROOT/one.ie/web/src/lib/generated/deploy-receipt.json"
   {
     mkdir -p "$(dirname "$_receipt")"
@@ -1116,10 +1058,8 @@ else
         (( ${#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.
+        # `${hfail[*]-}` not `${hfail[*]}` — bash 3.2 under `set -u` treats an
+        # EMPTY array as unbound.      incident:empty-array-unbound-bash32
         elif [[ " ${hfail[*]-} " == *" $_n "* ]]; then _h=false
         else                                        _h=true; fi
         printf '%s\n    {"name": "%s", "deployed": true, "healthy": %s}' "$_sep" "$_n" "$_h"
@@ -1133,17 +1073,9 @@ 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.
+# Post-deploy Lighthouse on the LIVE site. ADVISORY — the ENFORCED ratchet is
+# `bun run speed` pre-deploy against the local build. Exit 2 = INCONCLUSIVE and
+# is never a pass.                                incident:speed-step-detached
 if (( DRY )); then
   echo "  (dry run — speed check skipped)" | tee -a "$LOG"
 elif [[ "${SKIP_SPEED:-0}" == "1" ]]; then
@@ -1151,13 +1083,9 @@ elif [[ "${SKIP_SPEED:-0}" == "1" ]]; then
 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.
+  # One verdict function for both the inline and the detached path. bad() only
+  # PRINTS here: Step 9 runs after the ship, so it reports and does not block.
+  #                                             incident:speed-step-detached
   speed_verdict() {
     grep -E 'perf=|faster|SLOWER|performance:|advisory only' "$sp_out" | sed 's/^/    /' | tee -a "$LOG" || true
     case "$1" in
@@ -1179,14 +1107,9 @@ else
     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.
+    # DETACHED by default — it was 166s of a 227s pipeline, after the site had
+    # already shipped and passed health. Bounded so a hung Chrome cannot outlive
+    # the deploy.                                incident:speed-step-detached
     (
       run_bounded "${SPEED_TIMEOUT:-600}" "${sp_cmd[@]}" >"$sp_out" 2>&1
       rc=$?
@@ -1213,11 +1136,9 @@ say "  Health:     $HEALTH_REPORT"
 [[ -n "${GZIP_HINT:-}" ]] && say "  Bundle:     $GZIP_HINT"
 say "  Log:        $LOG"
 
-# The record the /deploy page renders. It runs on BOTH exits — a degraded deploy
-# is the run most worth having a timing for, and a record that only ever holds
-# green runs is a record that cannot be read for a trend. Guarded so a recorder
-# fault can never turn a good deploy into a bad exit: `|| true`, and the phases
-# come from arrays the gates already filled.
+# The record the /deploy page renders, on BOTH exits — a record holding only
+# green runs cannot be read for a trend. Guarded: a recorder fault must never
+# turn a good deploy into a bad exit.       incident:deploy-record-trunk-leg
 _record_run() {
   local verdict="$1"
   [[ -x "$ROOT/.claude/scripts/deploy-record.sh" ]] || return 0
@@ -1237,14 +1158,9 @@ _record_run() {
     args+=(--phase "${GATE_NAMES[$i]}:$(( GATE_T[i] - GATE_T0 )):$(( GATE_DUR[i] < 0 ? 0 : GATE_DUR[i] )):gate:$st")
   done
   bash "$ROOT/.claude/scripts/deploy-record.sh" "${args[@]}" >/dev/null 2>&1 || true
-  # THE TRUNK LEG. The row lands in the PRIMARY worktree, where a commit can
-  # pick it up — and nothing commits it, so /deploy (which renders that file at
-  # BUILD time) never sees it. Two production ships were lost that way in two
-  # days. It is not automated: main receives merges, never edits, and a
-  # recorder that pushed its own row would invent a door past that loop and
-  # need credentials at ship time. So it is made impossible to miss instead —
-  # printed here, at the moment it becomes true. Never fatal: a LOGGING debt
-  # must not fail a ship.
+  # THE TRUNK LEG. The row lands in the PRIMARY worktree and NOTHING commits it,
+  # so /deploy never renders it until someone does. Deliberately manual, and
+  # printed at the moment it becomes true.  incident:deploy-record-trunk-leg
   local pend; pend="$(bash "$ROOT/.claude/scripts/deploy-record.sh" --pending 2>/dev/null)" || true
   [[ -n "$pend" ]] && say "$pend"
   return 0
@@ -1255,10 +1171,8 @@ if (( ${#hfail[@]} )); then
   _emit_verdict red
   _record_run degraded
   # A degraded ship is an outcome. Close it as one.
-  # --only dims,feedback: `deploy` is a label, not a plan slug — without --tid the
-  # task leg resolves it through the `slug:` tag door and would close a plan named
-  # deploy if one ever existed. The deploy record is deploy-record.sh's job; what
-  # is true to write here is the pheromone.
+  # --only dims,feedback: `deploy` is a LABEL, not a plan slug — the task leg
+  # would close a plan named deploy.        incident:deploy-record-trunk-leg
   bash "$(dirname "${BASH_SOURCE[0]}")/do-close.sh" deploy --status failed --only dims,feedback || true
   say ""
   bad "degraded — unhealthy: ${hfail[*]}"