@biffo/cli 0.296.13 → 0.296.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.296.13",
+  "version": "0.296.15",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",

package/scripts/pg-test-db.sh

@@ -43,6 +43,7 @@
 #   eval "$(sh scripts/pg-test-db.sh --export)"   # export BIFFO_TEST_PG_DSN and TABSII_TEST_PG_DSN
 #   sh scripts/pg-test-db.sh                      # print the DSN on stdout
 #   sh scripts/pg-test-db.sh --recreate           # force a rebuild
+#   sh scripts/pg-test-db.sh --reap               # housekeeping only: reap and exit
 #
 # Only the DSN reaches stdout, so it is safe to capture; progress goes to stderr.
 #
@@ -164,10 +165,12 @@ CONTAINER="${BIFFO_PG_CONTAINER:-biffo-pg-test-$_checkout_suffix}"
 
 RECREATE=0
 EXPORT=0
+REAP_ONLY=0
 for arg in "$@"; do
   case "$arg" in
     --recreate) RECREATE=1 ;;
     --export) EXPORT=1 ;;
+    --reap) REAP_ONLY=1 ;;
     -h | --help)
       sed -n '2,72p' "$0" | sed 's/^#\{1,2\} \{0,1\}//'
       exit 0
@@ -250,6 +253,7 @@ if [ "$BIFFO_PG_REAP_HOURS" -gt 0 ] 2>/dev/null && command -v docker >/dev/null
     say "cannot compute a reap cutoff on this date(1); skipping container reaping"
   else
     _reaped=0
+    _reaped_gone=0
     _considered=0
     # TWO filters, not one literal name (#1383). The label is what containers
     # created from here now carry; the name prefix keeps covering every one
@@ -272,14 +276,65 @@ if [ "$BIFFO_PG_REAP_HOURS" -gt 0 ] 2>/dev/null && command -v docker >/dev/null
       _made=$(docker inspect -f '{{.Created}}' "$_c" 2>/dev/null | cut -c1-19)
       [ -z "$_made" ] && continue
       _considered=$((_considered + 1))
+      # ── Ownership beats age, where ownership is knowable ─────────────────
+      #
+      # Age was only ever a PROXY. The container is keyed to a checkout
+      # (see `CONTAINER` above), so the honest question is not "is this old?"
+      # but "does the checkout that owns it still exist?" -- and once the
+      # worktree is deleted the answer is a fact, not an estimate. A container
+      # whose checkout is gone can never be reused by anything, so there is no
+      # 4-second-rebuild trade to weigh: it is pure garbage the moment the
+      # directory disappears.
+      #
+      # Measured 2026-08-22 on one workstation: 42 live containers, of which 19
+      # belonged to checkouts that no longer existed. Under the age rule alone
+      # those 19 each held a running Postgres and ~500MB for up to 24 more
+      # hours -- and #703's real complaint was never disk, it was that these
+      # compete for the same page cache and I/O as the lane being timed.
+      #
+      # The path is read from a LABEL SET AT CREATION, never derived from the
+      # container's name. Deriving it would mean hashing candidate paths to see
+      # which produces this suffix, and the `biffo-pg-test-` prefix is shared by
+      # every repo in the estate -- so a run in one repo, finding no matching
+      # worktree of its OWN, would confidently reap a container another repo's
+      # test lane was mid-run against. The label makes the claim self-describing
+      # and repo-independent.
+      #
+      # Containers created before this label existed report an empty value and
+      # fall through to the age rule below, exactly as `biffo.ephemeral=1`
+      # migrated in (#1383). Nothing is stranded; they simply age out once.
+      _owner=$(docker inspect -f '{{index .Config.Labels "biffo.checkout"}}' "$_c" 2>/dev/null)
+      if [ -n "$_owner" ] && [ "$_owner" != "<no value>" ] && [ ! -d "$_owner" ]; then
+        if docker rm -f -v "$_c" >/dev/null 2>&1; then
+          _reaped=$((_reaped + 1))
+          _reaped_gone=$((_reaped_gone + 1))
+        fi
+        continue
+      fi
       # Both are UTC ISO-8601 to the second, so a string compare IS a time
       # compare -- no epoch conversion, and portable across date(1) flavours.
       if awk -v a="$_made" -v b="$_reap_cutoff" 'BEGIN { exit !(a < b) }'; then
-        docker rm -f "$_c" >/dev/null 2>&1 && _reaped=$((_reaped + 1))
+        # `-v` REMOVES THE CONTAINER'S ANONYMOUS VOLUME WITH IT.
+        #
+        # Without it every reap orphans a full Postgres data directory. Measured on one
+        # workstation 2026-08-20: 413 dangling volumes holding 104.8GB -- 95% of all local
+        # volume space -- against 11 live containers totalling 2.5MB. The containers were
+        # tidied and their data was not, so the leak grew by roughly a database per reap
+        # and nothing pointed at it.
+        #
+        # It is invisible by construction: `docker ps` looks clean, the reaper reports how
+        # many it removed, and the space is only findable with `docker volume ls -qf
+        # dangling=true`. The first symptom is a full disk somewhere unrelated.
+        docker rm -f -v "$_c" >/dev/null 2>&1 && _reaped=$((_reaped + 1))
       fi
     done
-    [ "$_reaped" -gt 0 ] &&
-      say "reaped $_reaped of $_considered container(s) unused for over ${BIFFO_PG_REAP_HOURS}h (set BIFFO_PG_REAP_HOURS=0 to disable)"
+    # Two reasons, counted apart. A single total would let the cheap, certain
+    # rule and the age guess read as one number, and the whole point of the
+    # ownership rule is that it is NOT a guess -- if it ever reaps something
+    # still wanted, that total must say so on its own.
+    if [ "$_reaped" -gt 0 ]; then
+      say "reaped $_reaped of $_considered container(s): $_reaped_gone whose checkout no longer exists, $((_reaped - _reaped_gone)) unused for over ${BIFFO_PG_REAP_HOURS}h (set BIFFO_PG_REAP_HOURS=0 to disable)"
+    fi
 
     # ── What the reaper can SEE but must not touch ──────────────────────────
     #
@@ -330,10 +385,31 @@ if [ "$BIFFO_PG_REAP_HOURS" -gt 0 ] 2>/dev/null && command -v docker >/dev/null
         say "NOT reaped -- Postgres containers over ${BIFFO_PG_REAP_HOURS}h old that this script did not create:"
         for _u in $_unclaimed; do say "  $_u"; done
         say "  A stale one costs test failures that belong to nobody (#1383). Remove by hand"
-        say "  (docker rm -f <name>), or start it with --label biffo.ephemeral=1 to have it reaped."
+        say "  (docker rm -f -v <name> -- the -v matters, or its data volume is orphaned),"
+        say "  or start it with --label biffo.ephemeral=1 to have it reaped."
       fi
     }
   fi
+
+  # `--reap` is housekeeping ONLY: reap, report, and stop before starting or
+  # touching a server.
+  #
+  # The reaper is otherwise LAZY -- it runs only when something else runs the
+  # lane, so the moment the fleet goes quiet nothing reclaims anything and the
+  # mess sits until the next test. That is the opposite of what is wanted: idle
+  # is exactly when reclaiming is free. This flag is the callable form, so a
+  # worktree teardown or a periodic sweep can collect without standing up a
+  # Postgres nobody asked for.
+  if [ "$REAP_ONLY" -eq 1 ]; then
+    exit 0
+  fi
+fi
+
+# Guard the case above: with reaping disabled there is nothing for `--reap` to
+# do, and it must still not fall through into starting a server.
+if [ "$REAP_ONLY" -eq 1 ]; then
+  say "reaping is disabled (BIFFO_PG_REAP_HOURS=0); nothing to do"
+  exit 0
 fi
 
 if ! psql_admin -c 'SELECT 1' >/dev/null 2>&1; then
@@ -352,7 +428,11 @@ if ! psql_admin -c 'SELECT 1' >/dev/null 2>&1; then
     # is still scanned, but it only ever described containers this script named;
     # anything started under another name was outside the reaper's denominator
     # entirely. A label travels with the container whatever it is called.
+    # `biffo.checkout` is what makes the container's owner knowable after the
+    # fact. The reaper above uses it to remove a container the moment its
+    # checkout is deleted, rather than waiting out a 24-hour proxy.
     docker run -d --name "$CONTAINER" --label biffo.ephemeral=1 \
+      --label "biffo.checkout=$REPO_ROOT" \
       -e POSTGRES_PASSWORD="$PASS" -p "$PORT:5432" "$IMAGE" >/dev/null
   fi
   # Polled, not slept: a cold image pull and a warm restart differ by an order of

package/scripts/wait-for-checks.sh

@@ -98,10 +98,37 @@
 #   anything     keep waiting on the checks as before. An unreadable field
 #   else         (old gh, missing scope) must never become a verdict.
 #
+# ## A wait that outlives its caller is worse than no wait
+#
+# This script's timeout says how long IT will wait. It said nothing about how
+# long its CALLER has left, and that gap loses whole sessions.
+#
+# Measured 2026-08-22, biffo-fleet Foreman `7d362ba7`, which runs under
+# `timeout 3300`. It pushed a commit at 05:37:03 and started this script at
+# 05:37:04 with about five minutes of its 55-minute budget left. CI was
+# genuinely in flight and would have concluded at 05:48:18 — a correct ~11
+# minute wait. The session was SIGKILLed at 05:42:45, this script returned
+# **137**, and the turn was lost mid-flight: no verdict, no cost record, the
+# tick reporting `cost=UNKNOWN tokens=UNKNOWN`. Nothing was wrong with the
+# checks or with the waiting; the wait could not fit in the time left and
+# neither side knew it. It was the eleventh such kill in three days.
+#
+# So a caller that knows when it dies can say so:
+#
+#   WAIT_FOR_CHECKS_DEADLINE  absolute unix epoch the CALLER dies at
+#   WAIT_FOR_CHECKS_MARGIN    seconds to leave it to react (default 60)
+#
+# The effective deadline becomes the EARLIER of its own timeout and that bound,
+# and if not even one poll fits it exits 2 immediately — before any API call —
+# rather than starting a wait it cannot finish. Both remain exit 2, "cannot
+# tell", never a pass: "ran out of time" and "checks are green" must never be
+# the same answer. Unset, nothing changes.
+#
 # ## Usage
 #
 #   sh scripts/wait-for-checks.sh <pr-number> [-R owner/repo]
 #                                 [--timeout SECONDS] [--interval SECONDS]
+#                                 [--deadline EPOCH]
 #
 # Requires `gh`, authenticated. Uses gh's embedded jq, so no jq binary is needed.
 
@@ -111,6 +138,8 @@ PR=""
 REPO=""
 TIMEOUT="${WAIT_FOR_CHECKS_TIMEOUT:-1800}"
 INTERVAL="${WAIT_FOR_CHECKS_INTERVAL:-30}"
+SESSION_DEADLINE="${WAIT_FOR_CHECKS_DEADLINE:-}"
+MARGIN="${WAIT_FOR_CHECKS_MARGIN:-60}"
 
 usage() {
   # Print the whole header block, however long it grows: from line 2 up to the
@@ -134,6 +163,10 @@ while [ $# -gt 0 ]; do
       INTERVAL="${2:-}"
       shift 2
       ;;
+    --deadline)
+      SESSION_DEADLINE="${2:-}"
+      shift 2
+      ;;
     -h | --help) usage ;;
     *)
       PR="$1"
@@ -152,6 +185,24 @@ GREEN=$(printf '\033[32m')
 DIM=$(printf '\033[90m')
 OFF=$(printf '\033[0m')
 
+# --- Bound the wait by the CALLER's life, not only by our own timeout ----------
+#
+# A non-numeric or empty bound is IGNORED rather than read as zero: an unreadable
+# value must never become "no time left", which would turn a caller's typo into a
+# script that refuses to wait for anything.
+deadline=$(($(date +%s) + TIMEOUT))
+bounded_by_caller=0
+case "$SESSION_DEADLINE" in
+  '' | *[!0-9]*) : ;;
+  *)
+    caller_limit=$((SESSION_DEADLINE - MARGIN))
+    if [ "$caller_limit" -lt "$deadline" ]; then
+      deadline=$caller_limit
+      bounded_by_caller=1
+    fi
+    ;;
+esac
+
 gh_pr() {
   if [ -n "$REPO" ]; then gh pr "$@" --repo "$REPO"; else gh pr "$@"; fi
 }
@@ -176,6 +227,33 @@ case "$state" in
     ;;
 esac
 
+# Not even one poll fits in what the CALLER has left. Refuse BEFORE the polling
+# starts: being killed mid-wait costs the caller its whole turn, while exiting now
+# leaves it time to record what it already knows.
+#
+# TWO PLACEMENT RULES, both learned by getting them wrong (cli/src/lib/
+# wait-for-checks.test.ts caught both):
+#
+#   1. ONLY when a caller bound is actually in force. Keyed on the effective
+#      deadline alone, `--timeout 0` -- a deliberate, tested "one pass then
+#      report" -- started refusing to run at all. A caller's own short timeout is
+#      its own business; this bound is about the caller's LIFE, not its patience.
+#
+#   2. AFTER the MERGED/CLOSED fast path. Placed before it, an already-merged PR
+#      with no time left returned "cannot tell" instead of the exit 0 it had
+#      already earned. There is nothing to wait for there, so there is nothing to
+#      refuse. One state read is a cost worth paying to answer correctly.
+if [ "$bounded_by_caller" = "1" ] && [ "$deadline" -le "$(( $(date +%s) + INTERVAL ))" ]; then
+  left=$(( deadline - $(date +%s) ))
+  [ "$left" -lt 0 ] && left=0
+  echo "${RED}wait-for-checks: not enough time left to wait for PR $PR.${OFF}" >&2
+  echo "The caller dies in ${left}s (margin ${MARGIN}s) and one poll takes ${INTERVAL}s," >&2
+  echo "so this would be killed mid-wait, losing the turn without a verdict." >&2
+  echo "Re-run with more time, or raise the caller's budget." >&2
+  echo "Not a failure and not a pass: this is 'cannot tell'." >&2
+  exit 2
+fi
+
 # --- Signal 1: the checks branch protection says MUST report ------------------
 
 owner_repo="$REPO"
@@ -198,7 +276,7 @@ fi
 
 # --- Poll ---------------------------------------------------------------------
 
-deadline=$(($(date +%s) + TIMEOUT))
+# `deadline` and `bounded_by_caller` were settled above, before any API call.
 prev_count=-1
 rollup=""
 
@@ -298,7 +376,15 @@ EOF
 
   now=$(date +%s)
   if [ "$now" -ge "$deadline" ]; then
-    echo "${RED}wait-for-checks: timed out after ${TIMEOUT}s.${OFF}" >&2
+    if [ "$bounded_by_caller" = "1" ]; then
+      # Distinct wording on purpose: "the caller ran out" sends you to its budget,
+      # "we ran out" sends you to CI. Same exit code, different fix.
+      echo "${RED}wait-for-checks: stopped early — the caller's deadline arrived.${OFF}" >&2
+      echo "Checks had not concluded. Waiting longer would have been killed" >&2
+      echo "mid-wait instead of returning this. Raise the caller's budget." >&2
+    else
+      echo "${RED}wait-for-checks: timed out after ${TIMEOUT}s.${OFF}" >&2
+    fi
     if [ "$count" = "0" ]; then
       # The exact case the naive loop gets wrong, so name it explicitly.
       echo "No checks ever appeared on PR $PR. That is 'cannot tell', not 'green'." >&2