@oneie/claude 0.8.0 → 0.10.0

package/scripts/deploy-record.sh

@@ -0,0 +1,605 @@
+#!/usr/bin/env bash
+# deploy-record.sh — append one run to the record the /deploy page renders.
+#
+#   deploy-record.sh --door "land --pr --deploy" --target dev.one.ie \
+#     --branch feat/x --sha abc1234 --verdict red --wall 232.7 \
+#     --phase "sdk + tsc:0:33:gate:pass" --phase "vitest pool:33:199:gate:fail" \
+#     --note "four suites failed to import"
+#
+# WHY A FILE AND NOT A SIGNAL. `world:announce` fans a signal to whoever staked on
+# its tags and marks the delivery path; it is a router, not a log. Nothing it
+# writes is a table a public page can read back, and `deliverToSubscriber` lands
+# in a tenant's inbox — the wrong place and the wrong audience for "what shipped".
+# `factory.astro` already settled this shape for the same problem: it renders
+# `src/data/factory-check.json`, generated by a script, and its own comment says
+# it is data, not a live query.
+#
+# So the record is a committed JSON file. That is what makes it visible from the
+# deployed worker at all: a deploy runs on somebody's laptop, and `one-prod`
+# cannot read that laptop's disk. A run enters the record the moment its writer
+# commits, and never before — which is why the page labels the newest run with
+# its sha and lets the reader see for themselves whether prod is running it.
+#
+# NEWEST FIRST, capped. An unbounded log would grow the worker bundle with every
+# deploy; the page shows a window, not a history.
+#
+# WHY THE PRIMARY WORKTREE, NEVER $ROOT. A production ship runs deploy.sh from
+# `.release/` (`release.sh ship`), a LINKED worktree, so `${BASH_SOURCE[0]}/../..`
+# resolves THERE and this script used to append to `.release/`'s own TRACKED copy.
+# Two failures, both measured on 2026-09-07's 10:50Z production ship. It left the
+# release tree dirty, and `release.sh promote` refuses a dirty release tree (exit
+# 6, "release tree is dirty — the receipt would not describe what ships") — so one
+# recorded ship blocked the next promote until the file was restored by hand. And
+# nothing ever commits from `.release/`, so that ship's own record was written
+# where it could never land: its row is absent from origin/main to this day, and
+# the page has only ever shown `land` runs to dev.
+#
+# So the record lands in the PRIMARY worktree whichever tree the door ran from.
+# That is a seam, not a special case for `.release/`: every linked worktree has
+# both problems, and the primary tree is the only place a row has ever reached
+# trunk from — `git log -- one.ie/web/src/data/deploy-runs.json` is a list of
+# ordinary commits made there. A resolution that does not already hold the
+# record's directory falls back to $ROOT, so a bad resolution degrades to the old
+# behaviour instead of inventing a phantom ledger somewhere new.
+#
+# THE TRUNK LEG, and why it stops one command short of automatic. The row now
+# lands in the PRIMARY worktree, where a commit CAN pick it up — but nothing
+# commits it, and the primary tree is the one place in this repo that
+# structurally cannot push: `hook:branch-pin` pins it to `main`, it is
+# permanently dirty (99 uncommitted paths, 85 of them also changed on trunk,
+# measured 2026-09-08), and it sat 171 commits behind origin/main with no
+# fast-forward. A commit made there lands on a stale main. The leg cannot end
+# in the tree the row lands in.
+#
+# It is deliberately NOT pushed the rest of the way. `../CLAUDE.md § The dev →
+# prod loop` says main receives merges, never edits — trunk is reached through
+# `dev` and a pull request. A recorder that pushed its own row would invent a
+# seventh door past the loop this repo just locked; it would need credentials
+# and a network at ship time, which a deploy must never depend on; and it would
+# race the other sessions rewriting the same 12-row capped array. A silent
+# failed push is precisely the failure this script was fixed for on 2026-09-08:
+# a record written where nobody looks. Automating it would rebuild that.
+#
+# What IS removed is having to remember, and having to notice. Pending is a
+# computable fact with a named exit code and a one-command committer:
+#
+#   --pending   the runs landing would ADD to the trunk ref (not merely the
+#               ones it lacks: see below). Exit 6 when there are
+#               any, silent 0 when there are none. deploy.sh and land.sh print
+#               it in their own report, inside `|| true` — a LOGGING debt must
+#               never fail a ship. (verify-fast's deferred-pin ledger refuses a
+#               deploy; that is a TEST debt, and this is not one.)
+#               It reads two states and prints the instruction that fits: no
+#               row committed anywhere, or already committed on a branch that a
+#               worktree has checked out — which is exit 6 just the same, because
+#               a row on a branch has not reached trunk.
+#   --land      the leg itself, run from a worktree cut from trunk: union the
+#               pending rows into THIS tree's copy, stage EXACTLY one path,
+#               commit. It refuses on the primary tree (exit 7), it never
+#               pushes, and the branch reaches trunk through land.sh like any
+#               other branch.
+#
+# ONE PATH, EVER. ~7 sessions edit the shared tree concurrently, so a blanket
+# stage sweeps a neighbour's uncommitted work into this commit — which is what
+# `hook:git-add-guard` refuses when a human types it. That hook is PreToolUse on
+# a human's Bash call and does not police what a script does internally, so
+# --self-test is the enforcement: it dirties a neighbouring TRACKED file, lands,
+# and asserts both halves — the commit names exactly one path, AND the
+# neighbour is STILL dirty afterwards. Gutted to the blanket form, both fail.
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+REL="one.ie/web/src/data/deploy-runs.json"
+# The primary worktree, or $ROOT when there is no answer to trust. `git worktree
+# list` prints the primary tree FIRST — that is the documented order, and it is
+# the only fact this needs. `substr($0,10)` rather than `$2` so a path with a
+# space in it survives.
+_record_root() {
+  local primary
+  command -v git >/dev/null 2>&1 || { printf '%s\n' "$ROOT"; return 0; }
+  primary="$(git -C "$ROOT" worktree list --porcelain 2>/dev/null \
+             | awk '/^worktree /{print substr($0,10); exit}')"
+  if [ -n "$primary" ] && [ -d "$primary/${REL%/*}" ]; then
+    printf '%s\n' "$primary"
+  else
+    printf '%s\n' "$ROOT"
+  fi
+}
+FILE="${DEPLOY_RECORD_FILE:-$(_record_root)/$REL}"
+KEEP="${DEPLOY_RECORD_KEEP:-12}"
+
+# The ref a row must reach to count as recorded. origin/main IS trunk here; the
+# fallbacks exist so a fresh clone or a --self-test sandbox gets a real answer
+# rather than a silent empty set, which would read as "nothing pending".
+_trunk_ref() { # <repo-root>
+  local R="$1" r
+  [ -n "${DEPLOY_RECORD_TRUNK:-}" ] && { printf '%s\n' "$DEPLOY_RECORD_TRUNK"; return 0; }
+  for r in origin/main main; do
+    git -C "$R" rev-parse --verify -q "$r" >/dev/null 2>&1 && { printf '%s\n' "$r"; return 0; }
+  done
+  printf 'HEAD\n'
+}
+
+# The slice the record file holds, given a base and rows to add. ONE definition,
+# used both to answer "what is pending" and to land it — two spellings of the
+# same slice is the drift `test-full.sh` exists to prevent, and here it produced
+# a real defect: pending was "what trunk lacks", which counted rows the cap can
+# never admit. Those are EXPIRED, not pending, and no amount of landing removes
+# them, so --pending fired on every deploy forever. Pending is now what the union
+# would actually ADD.
+_JQ_UNION='
+  def k: "\(.at)|\(.door // "")|\(.sha // "")|\(.target // "")";
+  def _union($base; $add): (($base + $add) | unique_by(k) | sort_by(.at) | reverse | .[0:$keep]);
+'
+
+# The runs landing would ADD to the trunk ref — not merely the ones it lacks.
+# A row older than a full cap of trunk rows can never be admitted, so reporting
+# it is reporting work nobody can do. Returned as a JSON array. Keyed on
+# at+door+sha+target: `at` is second-resolution and two doors can finish in the
+# same second, so `at` alone is not a key. Any doubt answers [] — a nudge that
+# fires on a bad read is a nudge nobody reads.
+_pending_rows() {
+  local dir R rel hf ref
+  command -v git >/dev/null 2>&1 || { printf '[]\n'; return 0; }
+  [ -f "$FILE" ] || { printf '[]\n'; return 0; }
+  dir="$(cd "$(dirname "$FILE")" 2>/dev/null && pwd)" || { printf '[]\n'; return 0; }
+  R="$(git -C "$dir" rev-parse --show-toplevel 2>/dev/null)"
+  [ -n "$R" ] || { printf '[]\n'; return 0; }
+  rel="${FILE#"$R"/}"
+  ref="$(_trunk_ref "$R")"
+  hf="$(mktemp)"
+  git -C "$R" show "$ref:$rel" > "$hf" 2>/dev/null || :
+  [ -s "$hf" ] || printf '{"runs":[]}' > "$hf"
+  jq -n --slurpfile w "$FILE" --slurpfile h "$hf" --argjson keep "$KEEP" "$_JQ_UNION"'
+    ((($h[0] // {}).runs) // []) as $base
+    | ((($w[0] // {}).runs) // []) as $work
+    | ($base | map(k)) as $seen
+    | _union($base; $work)
+    | map(. as $r | select(($seen | index($r|k)) == null))' 2>/dev/null || printf '[]\n'
+  rm -f "$hf"
+}
+
+# Where the pending rows already sit, if anywhere. A row committed on a branch
+# still has not reached trunk, so it is still pending — but "nobody has committed
+# these" and "land the branch" are different instructions, and printing the wrong
+# one on every ship is exactly how a nudge stops being read. Candidates are the
+# branches actually CHECKED OUT in worktrees: they are the only places --land can
+# have put a row (it refuses on the primary tree), and there are ~9 of them
+# against 63 local branches. Matched on the newest pending row, which is one jq
+# per candidate rather than a set comparison.
+_pending_inflight() { # <repo-root> <rel> <key-of-newest> → branch names
+  local R="$1" rel="$2" key="$3" ref name cand out=""
+  for ref in $(git -C "$R" worktree list --porcelain 2>/dev/null | awk '/^branch /{print $2}'); do
+    name="${ref#refs/heads/}"
+    cand="$(git -C "$R" show "$ref:$rel" 2>/dev/null)" || continue
+    [ -n "$cand" ] || continue
+    [ "$(jq -r --arg k "$key" '[.runs[]?
+           | select("\(.at)|\(.door // "")|\(.sha // "")|\(.target // "")" == $k)]
+          | length' <<<"$cand" 2>/dev/null)" = "0" ] && continue
+    out="$out $name"
+  done
+  # The leading space is deliberate: callers interpolate this straight after a
+  # colon and straight after a command name, and both need the separator.
+  printf '%s\n' "$out"
+}
+
+# The nudge. Silent and 0 when nothing is pending — a line printed on every
+# deploy is a line nobody reads. Exit 6 is the whole point: it is checkable.
+_pending_report() {
+  local rows n newest key onbr dir R rel
+  rows="$(_pending_rows)"
+  n="$(jq 'length' <<<"$rows" 2>/dev/null)" || n=0
+  case "$n" in ''|*[!0-9]*) n=0 ;; esac
+  [ "$n" -gt 0 ] || return 0
+  newest="$(jq -r 'sort_by(.at) | reverse | .[0]
+                   | "\(.at)  \(.door)  \(.sha // "—")  \(.verdict // "—")"' <<<"$rows")"
+  key="$(jq -r 'sort_by(.at) | reverse | .[0]
+                | "\(.at)|\(.door // "")|\(.sha // "")|\(.target // "")"' <<<"$rows")"
+  # Recomputed, never inherited: _pending_rows runs inside a command
+  # substitution, so anything it sets lives and dies in that subshell.
+  dir="$(cd "$(dirname "$FILE")" 2>/dev/null && pwd)" || dir="."
+  R="$(git -C "$dir" rev-parse --show-toplevel 2>/dev/null)" || R=""
+  rel="$REL"; [ -n "$R" ] && rel="${FILE#"$R"/}"
+  onbr=""; [ -n "$R" ] && onbr="$(_pending_inflight "$R" "$rel" "$key")"
+  if [ -n "$onbr" ]; then
+    printf '%s\n' \
+"[deploy-record] $n run(s) recorded, already committed on:$onbr — but NOT IN TRUNK yet." \
+"                newest:  $newest" \
+"                the branch is all that is left:" \
+"                  bash .claude/scripts/land.sh${onbr}"
+  else
+    printf '%s\n' \
+"[deploy-record] $n run(s) recorded but NOT IN TRUNK. /deploy renders this file at BUILD" \
+"                time, so a row nobody commits never reaches the page." \
+"                newest:  $newest" \
+"                held in: $FILE" \
+"                land it, from a worktree cut from trunk — never the primary tree:" \
+"                  bash .claude/scripts/deploy-record.sh --land"
+  fi
+  return 6
+}
+
+DOOR="" TARGET="" BRANCH="" SHA="" VERDICT="" WALL="" NOTE="" SELF_TEST=0 PENDING=0 LAND=0
+PHASES=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --door) DOOR="${2:-}"; shift 2 ;;
+    --target) TARGET="${2:-}"; shift 2 ;;
+    --branch) BRANCH="${2:-}"; shift 2 ;;
+    --sha) SHA="${2:-}"; shift 2 ;;
+    --verdict) VERDICT="${2:-}"; shift 2 ;;
+    --wall) WALL="${2:-}"; shift 2 ;;
+    --note) NOTE="${2:-}"; shift 2 ;;
+    --phase) PHASES+=("${2:-}"); shift 2 ;;
+    --self-test) SELF_TEST=1; shift ;;
+    --pending) PENDING=1; shift ;;
+    --land) LAND=1; shift ;;
+    -h|--help) sed -n '2,12p' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) echo "deploy-record.sh: unknown flag '$1'" >&2; exit 2 ;;
+  esac
+done
+
+command -v jq >/dev/null 2>&1 || { echo "deploy-record.sh: needs jq" >&2; exit 3; }
+
+_emit() { # writes the new record file to stdout, given the current one on stdin
+  local phases_json='[]' p name start dur kind state
+  for p in ${PHASES[@]+"${PHASES[@]}"}; do
+    IFS=':' read -r name start dur kind state <<<"$p"
+    phases_json="$(jq -c --arg n "$name" --argjson s "${start:-0}" --argjson d "${dur:-0}" \
+      --arg k "${kind:-gate}" --arg st "${state:-unrun}" \
+      '. + [{name:$n, start:$s, dur:$d, kind:$k, state:$st}]' <<<"$phases_json")"
+  done
+  jq --arg door "$DOOR" --arg target "$TARGET" --arg branch "$BRANCH" --arg sha "$SHA" \
+     --arg verdict "${VERDICT:-unknown}" --arg note "$NOTE" \
+     --argjson wall "${WALL:-0}" --argjson phases "$phases_json" \
+     --arg at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --argjson keep "$KEEP" \
+     '{runs: ([{at:$at, door:$door, target:$target, branch:$branch, sha:$sha,
+                verdict:$verdict, wall:$wall, note:$note, phases:$phases}]
+              + (.runs // []))[0:$keep]}'
+}
+
+if (( SELF_TEST )); then
+  # The red proof: a recorder that silently writes nothing, or drops the cap, is
+  # worse than no recorder — the page would render a stale run as the current one.
+  t="$(mktemp -d)"; f="$t/runs.json"; fail=0
+  ok(){ printf '  \033[32m✓\033[0m %s\n' "$1"; }
+  bad(){ printf '  \033[31m✗\033[0m %s\n' "$1"; fail=1; }
+  printf '{"runs":[]}' > "$f"
+  for i in 1 2 3; do
+    DEPLOY_RECORD_FILE="$f" DEPLOY_RECORD_KEEP=2 bash "${BASH_SOURCE[0]}" \
+      --door "d$i" --target t --verdict green --wall "$i" --phase "p:0:1:gate:pass" >/dev/null
+  done
+  n="$(jq '.runs|length' "$f")"
+  [ "$n" = "2" ] && ok "cap holds (3 written, 2 kept)" || bad "cap ignored — kept $n"
+  [ "$(jq -r '.runs[0].door' "$f")" = "d3" ] && ok "newest first" || bad "order wrong"
+  [ "$(jq -r '.runs[0].phases[0].state' "$f")" = "pass" ] && ok "phase parsed" || bad "phase lost"
+  # a run with no phases must still record — a gate that died before phase 1 is a fact
+  DEPLOY_RECORD_FILE="$f" bash "${BASH_SOURCE[0]}" --door bare --verdict red --wall 1 >/dev/null
+  [ "$(jq -r '.runs[0].phases|length' "$f")" = "0" ] && ok "a phase-less run still records" || bad "dropped a phase-less run"
+
+  # ── the release-worktree property ────────────────────────────────────────
+  # A production ship runs deploy.sh from `.release/`, a LINKED worktree. The
+  # bar is two-sided and both sides matter: the tree it ran from must stay
+  # CLEAN (its cleanliness is the receipt's whole premise), and the run must
+  # still reach the file the /deploy page imports. A recorder that satisfies
+  # only one of those is the defect this check exists for.
+  #
+  # The sandbox is built to look like the real thing: the script and a seeded
+  # record are COMMITTED first, then the linked worktree is added, so both
+  # trees carry them tracked and clean and `git status --porcelain` can be
+  # asserted bare — no pathspec, nothing filtered out.
+  _sb() { # <dir> [gut: file|land|pending|expire] — a repo shaped like this one:
+          # a primary tree, a release-shaped worktree, and a feature worktree.
+          # The seed record carries a row and there is a tracked NEIGHBOUR file,
+          # because the staging assertions need something to sweep and the union
+          # assertion needs a row trunk already holds.
+    local s="$1" gut="${2:-}"
+    mkdir -p "$s/main/.claude/scripts" "$s/main/one.ie/web/src/data"
+    cp "${BASH_SOURCE[0]}" "$s/main/.claude/scripts/deploy-record.sh"
+    case "$gut" in
+      file)
+        # RED HALF for the release-worktree property. Restore the one line as it
+        # stood before 2026-09-08 — the record resolved off $ROOT, so a linked
+        # worktree wrote its own tracked copy.
+        sed 's|^FILE=.*|FILE="${DEPLOY_RECORD_FILE:-$ROOT/one.ie/web/src/data/deploy-runs.json}"|' \
+          "$s/main/.claude/scripts/deploy-record.sh" > "$s/g" && mv "$s/g" "$s/main/.claude/scripts/deploy-record.sh"
+        ;;
+      land)
+        # RED HALF for ONE PATH, EVER. Replace --land's explicit-path stage with
+        # the blanket form this door exists in order not to be. Nothing else
+        # about --land changes, so a green result here can only mean the staging
+        # rule was never what the assertions were reading.
+        sed 's|^  git -C "$here" add -- "$REL".*|  git -C "$here" add -A|' \
+          "$s/main/.claude/scripts/deploy-record.sh" > "$s/g" && mv "$s/g" "$s/main/.claude/scripts/deploy-record.sh"
+        ;;
+      expire)
+        # RED HALF for expiry. Restore the definition this replaced — pending as
+        # "what trunk lacks" rather than "what landing would add". A row the cap
+        # can never admit then reads as pending, on every deploy, forever.
+        sed 's#^    | _union($base; $work)$#    | $work#' \
+          "$s/main/.claude/scripts/deploy-record.sh" > "$s/g" && mv "$s/g" "$s/main/.claude/scripts/deploy-record.sh"
+        ;;
+      pending)
+        # RED HALF for the nudge. Blind _pending_rows to []. A checker that stays
+        # green against a recorder which can never see a pending row measures
+        # nothing at all.
+        awk '/^_pending_rows\(\) \{$/ {print "_pending_rows() { printf \"[]\\n\"; }"; sk=1; next}
+             sk && /^\}$/ {sk=0; next} sk {next} {print}' \
+          "$s/main/.claude/scripts/deploy-record.sh" > "$s/g" && mv "$s/g" "$s/main/.claude/scripts/deploy-record.sh"
+        ;;
+    esac
+    printf '%s' '{"runs":[{"at":"2026-01-01T00:00:00Z","door":"seed","target":"t","branch":"b","sha":"seed0001","verdict":"green","wall":1,"note":"","phases":[]}]}' \
+      > "$s/main/one.ie/web/src/data/deploy-runs.json"
+    printf 'a neighbour, tracked and clean\n' > "$s/main/neighbour.txt"
+    git -C "$s/main" init -q -b main >/dev/null 2>&1 || git -C "$s/main" init -q >/dev/null 2>&1
+    git -C "$s/main" config user.email t@t >/dev/null 2>&1
+    git -C "$s/main" config user.name t >/dev/null 2>&1
+    git -C "$s/main" add .claude one.ie neighbour.txt >/dev/null 2>&1
+    git -C "$s/main" commit -qm seed >/dev/null 2>&1
+    git -C "$s/main" worktree add -q "$s/release" -b release >/dev/null 2>&1
+    git -C "$s/main" worktree add -q "$s/feat" -b feat >/dev/null 2>&1
+  }
+  _ship() { # <sandbox> — run the door the way `release.sh ship` runs it
+    ( cd "$1/release" && bash "$1/release/.claude/scripts/deploy-record.sh" \
+        --door "deploy full" --target prod --verdict green --wall 92 \
+        --phase "vitest:2:2:gate:pass" ) >/dev/null 2>&1
+  }
+
+  g="$(mktemp -d)"; _sb "$g"
+  _ship "$g"
+  gdirt="$(git -C "$g/release" status --porcelain)"
+  gmain="$(jq -r '.runs[0].door // "—"' "$g/main/one.ie/web/src/data/deploy-runs.json")"
+  [ -z "$gdirt" ] && ok "a ship from the release worktree leaves it CLEAN" \
+                  || bad "the release worktree was dirtied: $(printf '%s' "$gdirt" | tr '\n' ';')"
+  [ "$gmain" = "deploy full" ] && ok "…and the run still reaches the page's file in the primary tree" \
+                               || bad "the run was lost — primary tree's newest door is '$gmain'"
+
+  # The red half. Same two assertions, driven against the behaviour this fix
+  # replaced: BOTH must fail. A gut that only breaks one of them can still read
+  # green on the other, and a half-red proof proves half of nothing.
+  r="$(mktemp -d)"; _sb "$r" file
+  _ship "$r"
+  rdirt="$(git -C "$r/release" status --porcelain)"
+  rmain="$(jq -r '.runs[0].door // "—"' "$r/main/one.ie/web/src/data/deploy-runs.json")"
+  if [ -n "$rdirt" ] && [ "$rmain" != "deploy full" ]; then
+    ok "red proof — gutted to the old FILE=, the worktree goes dirty ($(printf '%s' "$rdirt" | tr -s ' ' | tr '\n' ';')) and the primary tree records nothing"
+  else
+    bad "red proof did not bite — dirty='$rdirt' primary-door='$rmain'; the green half above proves nothing"
+  fi
+  # ── the trunk leg: --pending and --land ──────────────────────────────────
+  # The 2026-09-08 fix put the row where a commit CAN pick it up. Nothing
+  # commits it, and the primary tree cannot push, so the leg is a worktree and
+  # land.sh. What is checked here is that the leg cannot be forgotten (pending
+  # is a computable fact with a red exit) and that walking it stages ONE path.
+
+  # --pending, both directions. Silent and 0 while trunk carries every run;
+  # exit 6 naming the ship the moment one is recorded and uncommitted.
+  q="$(mktemp -d)"; _sb "$q"
+  pq_out="$(cd "$q/feat" && bash "$q/feat/.claude/scripts/deploy-record.sh" --pending 2>&1)"; pq_rc=$?
+  { [ "$pq_rc" = 0 ] && [ -z "$pq_out" ]; } \
+    && ok "--pending is silent and 0 when trunk carries every run" \
+    || bad "--pending fired on a clean record (rc=$pq_rc) — a line that always prints is never read"
+  _ship "$q"
+  pd_out="$(cd "$q/feat" && bash "$q/feat/.claude/scripts/deploy-record.sh" --pending 2>&1)"; pd_rc=$?
+  case "$pd_out" in *"NOT IN TRUNK"*) pd_named=1 ;; *) pd_named=0 ;; esac
+  { [ "$pd_rc" = 6 ] && [ "$pd_named" = 1 ]; } \
+    && ok "--pending goes RED (exit 6) and names the run once a ship is recorded but uncommitted" \
+    || bad "--pending did not report the recorded ship (rc=$pd_rc, out='$(printf '%s' "$pd_out" | tr '\n' ';')')"
+
+  qr="$(mktemp -d)"; _sb "$qr" pending; _ship "$qr"
+  qr_out="$(cd "$qr/feat" && bash "$qr/feat/.claude/scripts/deploy-record.sh" --pending 2>&1)"; qr_rc=$?
+  { [ "$qr_rc" = 0 ] && [ -z "$qr_out" ]; } \
+    && ok "red proof — blinded to [], --pending calls a real pending ship a clean record" \
+    || bad "red proof did not bite — the blinded --pending still exited $qr_rc; the two checks above prove nothing"
+
+  # A row the cap can never admit is EXPIRED, not pending. Measured on the real
+  # repo before this was fixed: --land unioned 12 rows into a file already
+  # holding 12 and the cap dropped the 2 oldest, so once the branch merged,
+  # --pending reported those 2 on every deploy and every land, forever, and
+  # --land answered "already carries all 2" because the union was a no-op.
+  _expired_sb() { # <dir> [gut] — trunk holds a FULL cap of rows, all newer
+    _sb "$1" "${2:-}"
+    jq -n '{runs:[{at:"2026-02-02T00:00:00Z",door:"a",target:"t",branch:"b",sha:"aaa",verdict:"green",wall:1,note:"",phases:[]},
+                  {at:"2026-02-01T00:00:00Z",door:"b",target:"t",branch:"b",sha:"bbb",verdict:"green",wall:1,note:"",phases:[]}]}' \
+      > "$1/main/one.ie/web/src/data/deploy-runs.json"
+    git -C "$1/main" add -- one.ie/web/src/data/deploy-runs.json >/dev/null 2>&1
+    git -C "$1/main" commit -qm cap >/dev/null 2>&1
+    # …and one OLDER row in the working copy, which a cap of 2 can never admit
+    jq '.runs += [{at:"2026-01-01T00:00:00Z",door:"old",target:"t",branch:"b",sha:"ooo",verdict:"green",wall:1,note:"",phases:[]}]' \
+      "$1/main/one.ie/web/src/data/deploy-runs.json" > "$1/w" \
+      && mv "$1/w" "$1/main/one.ie/web/src/data/deploy-runs.json"
+  }
+  E="$(mktemp -d)"; _expired_sb "$E"
+  e_out="$(cd "$E/feat" && DEPLOY_RECORD_KEEP=2 bash "$E/feat/.claude/scripts/deploy-record.sh" --pending 2>&1)"; e_rc=$?
+  { [ "$e_rc" = 0 ] && [ -z "$e_out" ]; } \
+    && ok "a row the cap can never admit is EXPIRED, not pending — --pending stays silent" \
+    || bad "--pending reports a row landing could never add (rc=$e_rc) — it would fire on every deploy forever"
+
+  E2="$(mktemp -d)"; _expired_sb "$E2" expire
+  e2_out="$(cd "$E2/feat" && DEPLOY_RECORD_KEEP=2 bash "$E2/feat/.claude/scripts/deploy-record.sh" --pending 2>&1)"; e2_rc=$?
+  { [ "$e2_rc" = 6 ] && [ -n "$e2_out" ]; } \
+    && ok "red proof — on the old definition (what trunk LACKS) the expired row reads as pending, exit 6" \
+    || bad "red proof did not bite — the old definition exited $e2_rc; the check above proves nothing"
+
+  # ── ONE PATH, EVER ───────────────────────────────────────────────────────
+  # The load-bearing assertion. hook:git-add-guard refuses a blanket stage a
+  # HUMAN types; it is PreToolUse and does not police what a script does
+  # internally. So this is the enforcement, and it is two-sided on purpose: a
+  # mechanism that blanket-stages in a SECOND commit passes a one-sided check.
+  L="$(mktemp -d)"; _sb "$L"; _ship "$L"
+  printf 'a neighbour, edited by somebody else mid-run\n' >> "$L/feat/neighbour.txt"
+  l_out="$(cd "$L/feat" && bash "$L/feat/.claude/scripts/deploy-record.sh" --land 2>&1)"; l_rc=$?
+  l_names="$(git -C "$L/feat" show --name-only --pretty=format: HEAD | sed '/^$/d' | tr '\n' ' ' | sed 's/ $//')"
+  l_dirty="$(git -C "$L/feat" status --porcelain -- neighbour.txt)"
+  l_rec="$L/feat/one.ie/web/src/data/deploy-runs.json"
+  l_top="$(jq -r '.runs[0].door // "—"' "$l_rec" 2>/dev/null)"
+  l_seed="$(jq -r '[.runs[] | select(.sha == "seed0001")] | length' "$l_rec" 2>/dev/null)"
+  [ "$l_rc" = 0 ] && ok "--land walked the leg from a linked worktree" \
+                  || bad "--land exited $l_rc: $(printf '%s' "$l_out" | tr '\n' ';')"
+  [ "$l_names" = "$REL" ] && ok "--land's commit names EXACTLY one path ($l_names)" \
+                          || bad "--land's commit named '$l_names' — a neighbour was swept in"
+  [ -n "$l_dirty" ] && ok "…and the neighbour's edit is STILL uncommitted ($(printf '%s' "$l_dirty" | tr -s ' '))" \
+                    || bad "the neighbour's edit was swept into the commit — the whole reason git-add-guard exists"
+  [ "$l_top" = "deploy full" ] && ok "…and the pending ship reached this tree's record" \
+                              || bad "the pending ship did not land — newest door here is '$l_top'"
+  [ "$l_seed" = "1" ] && ok "…as a UNION — the row trunk already carried survives the merge" \
+                      || bad "the merge dropped trunk's own row (found $l_seed) — that is a copy, not a union"
+
+  # The nudge must tell the two states apart, or it prints the wrong instruction
+  # on every ship until the PR merges and stops being read. Two-sided: after
+  # --land the message names the BRANCH; before it, it must not.
+  li_out2="$(cd "$L/release" && bash "$L/release/.claude/scripts/deploy-record.sh" --pending 2>&1)"
+  case "$li_out2" in *"already committed on: feat"*) lf=1 ;; *) lf=0 ;; esac
+  case "$pd_out" in *"already committed on"*) lg=1 ;; *) lg=0 ;; esac
+  { [ "$lf" = 1 ] && [ "$lg" = 0 ]; } \
+    && ok "--pending tells the two states apart: 'already committed on: feat' after --land, and not before" \
+    || bad "--pending cannot tell a landed row from an unlanded one (after=$lf before=$lg)"
+
+  # The red half for both staging assertions. BOTH must fail: a gut that breaks
+  # only one of them can still read green on the other.
+  X="$(mktemp -d)"; _sb "$X" land; _ship "$X"
+  printf 'a neighbour, edited by somebody else mid-run\n' >> "$X/feat/neighbour.txt"
+  ( cd "$X/feat" && bash "$X/feat/.claude/scripts/deploy-record.sh" --land ) >/dev/null 2>&1
+  x_names="$(git -C "$X/feat" show --name-only --pretty=format: HEAD | sed '/^$/d' | tr '\n' ' ' | sed 's/ $//')"
+  x_dirty="$(git -C "$X/feat" status --porcelain -- neighbour.txt)"
+  if [ "$x_names" != "$REL" ] && [ -z "$x_dirty" ]; then
+    ok "red proof — gutted to the blanket stage, the commit names '$x_names' and the neighbour's edit is gone from the working tree"
+  else
+    bad "red proof did not bite — names='$x_names' neighbour-still-dirty='$x_dirty'; the staging checks above prove nothing"
+  fi
+
+  # --land refuses on the PRIMARY tree. A commit there lands on a stale, pinned
+  # main that cannot be pushed — the reason this leg is not automatic at all.
+  lp_before="$(git -C "$L/main" rev-parse HEAD)"
+  lp_out="$(cd "$L/main" && bash "$L/main/.claude/scripts/deploy-record.sh" --land 2>&1)"; lp_rc=$?
+  { [ "$lp_rc" = 7 ] && [ "$(git -C "$L/main" rev-parse HEAD)" = "$lp_before" ]; } \
+    && ok "--land refuses on the primary worktree (exit 7) and commits nothing there" \
+    || bad "--land ran on the primary tree (rc=$lp_rc) — that commit could never be pushed"
+
+  # And it refuses rather than commit AROUND another's staged path. The index is
+  # not this door's to edit; a partial-commit pathspec would have hidden this.
+  I="$(mktemp -d)"; _sb "$I"; _ship "$I"
+  printf 'staged by somebody else\n' >> "$I/feat/neighbour.txt"
+  git -C "$I/feat" add -- neighbour.txt >/dev/null 2>&1
+  li_before="$(git -C "$I/feat" rev-parse HEAD)"
+  li_out="$(cd "$I/feat" && bash "$I/feat/.claude/scripts/deploy-record.sh" --land 2>&1)"; li_rc=$?
+  { [ "$li_rc" = 9 ] && [ "$(git -C "$I/feat" rev-parse HEAD)" = "$li_before" ]; } \
+    && ok "--land refuses (exit 9) rather than commit around another's staged path" \
+    || bad "--land committed with a foreign path staged (rc=$li_rc)"
+
+  rm -rf "$q" "$qr" "$L" "$X" "$I" "$E" "$E2"
+  git -C "$g/main" worktree remove --force "$g/release" >/dev/null 2>&1
+  git -C "$r/main" worktree remove --force "$r/release" >/dev/null 2>&1
+  rm -rf "$g" "$r"
+  rm -rf "$t"
+  [ "$fail" = 0 ] && { echo "deploy-record.sh: all checks pass"; exit 0; }
+  echo "deploy-record.sh: FAILED"; exit 4
+fi
+
+# ── --pending ───────────────────────────────────────────────────────────────
+if (( PENDING )); then
+  _pending_report; exit $?
+fi
+
+# ── --land: the trunk leg ───────────────────────────────────────────────────
+# Union the pending rows into THIS worktree's copy, stage exactly one path,
+# commit. Never pushes: the branch reaches trunk through land.sh, the door the
+# loop already has.
+if (( LAND )); then
+  primary="$(_record_root)"
+  here="$(git rev-parse --show-toplevel 2>/dev/null)"
+  if [ -z "$here" ]; then
+    echo "deploy-record.sh --land: not inside a git worktree." >&2; exit 7
+  fi
+  if [ "$here" = "$primary" ]; then
+    {
+      echo "deploy-record.sh --land: refusing on the PRIMARY worktree."
+      echo "  It is pinned to main by hook:branch-pin, permanently dirty, and behind trunk,"
+      echo "  so a commit made here lands on a stale main and cannot be pushed. Cut a"
+      echo "  worktree and run this door there:"
+      echo "    bash .claude/scripts/worktree-up.sh deployrec --no-dev"
+      echo "    cd .claude/worktrees/deployrec && bash .claude/scripts/deploy-record.sh --land"
+    } >&2
+    exit 7
+  fi
+
+  rows="$(_pending_rows)"
+  n="$(jq 'length' <<<"$rows" 2>/dev/null)" || n=0
+  case "$n" in ''|*[!0-9]*) n=0 ;; esac
+  if [ "$n" -eq 0 ]; then
+    echo "[deploy-record] nothing pending — trunk already carries every recorded run."
+    exit 0
+  fi
+
+  # ONE PATH, EVER. If somebody else's work is already staged here, REFUSE
+  # rather than commit around it. A partial-commit pathspec would hide the
+  # collision instead of surfacing it, and the index is not this door's to edit.
+  others=""
+  while IFS= read -r stagedpath; do
+    [ -z "$stagedpath" ] && continue
+    [ "$stagedpath" = "$REL" ] && continue
+    others="$others $stagedpath"
+  done < <(git -C "$here" diff --cached --name-only 2>/dev/null)
+  if [ -n "$others" ]; then
+    {
+      echo "deploy-record.sh --land: the index here already holds:$others"
+      echo "  This door stages exactly one path and will not commit around another's work."
+      echo "  Commit or unstage that first."
+    } >&2
+    exit 9
+  fi
+
+  target="$here/$REL"
+  mkdir -p "$(dirname "$target")"
+  [ -f "$target" ] || printf '{"runs":[]}' > "$target"
+  # UNION, never copy. The primary tree's working copy has already dropped rows
+  # past the cap that trunk still carries — copying it over would DELETE them.
+  # Same shape _emit writes: unique, newest first, re-sliced at the cap.
+  ltmp="$(mktemp)"
+  if jq --argjson add "$rows" --argjson keep "$KEEP" "$_JQ_UNION"'
+       {runs: _union((.runs // []); $add)}' \
+       "$target" > "$ltmp" && [ -s "$ltmp" ]; then
+    mv "$ltmp" "$target"
+  else
+    rm -f "$ltmp"
+    echo "deploy-record.sh --land: could not merge into $target" >&2; exit 8
+  fi
+
+  branch="$(git -C "$here" rev-parse --abbrev-ref HEAD 2>/dev/null || echo HEAD)"
+  if git -C "$here" diff --quiet HEAD -- "$REL" 2>/dev/null; then
+    echo "[deploy-record] this tree already carries all $n run(s) — the branch is what is left:"
+    echo "                  bash .claude/scripts/land.sh $branch"
+    exit 0
+  fi
+
+  # THE ONE PATH. --self-test guts this line to the blanket form and asserts a
+  # neighbouring dirty file is swept in — that red half is the reason this line
+  # is a line and not a convenience.
+  git -C "$here" add -- "$REL" || { echo "deploy-record.sh --land: stage failed" >&2; exit 8; }
+
+  lmsg="$(printf '%s\n\n%s\n%s\n\n%s\n' \
+    "chore(deploy): the record's trunk leg — $n run(s) the primary tree was holding" \
+    "deploy.sh and land.sh write each run into the PRIMARY worktree's copy of $REL, and nothing commits it. /deploy renders that file at BUILD time — a deploy runs on a laptop and one-prod cannot read that disk — so a row nobody commits never reaches the page." \
+    "These are the runs trunk did not carry:" \
+    "$(jq -r 'sort_by(.at) | reverse | .[]
+              | "  \(.at)  \(.door)  \(.sha // "—")  \(.verdict // "—")"' <<<"$rows")")"
+  if ! git -C "$here" commit -q -m "$lmsg"; then
+    echo "deploy-record.sh --land: commit failed" >&2; exit 8
+  fi
+  echo "[deploy-record] landed $n run(s) on $branch — staged one path: $REL"
+  echo "                trunk is one door away:  bash .claude/scripts/land.sh $branch"
+  exit 0
+fi
+
+[ -n "$DOOR" ] || { echo "deploy-record.sh: --door is required" >&2; exit 2; }
+mkdir -p "$(dirname "$FILE")"
+[ -f "$FILE" ] || printf '{"runs":[]}' > "$FILE"
+tmp="$(mktemp)"
+if _emit < "$FILE" > "$tmp" && [ -s "$tmp" ]; then
+  mv "$tmp" "$FILE"
+  echo "[deploy-record] $DOOR → ${TARGET:-—} · ${VERDICT:-unknown} · ${WALL:-0}s"
+  _pending_report || true
+else
+  rm -f "$tmp"
+  echo "[deploy-record] could not write $FILE — run NOT recorded" >&2
+  exit 5
+fi