fix(tooling): stop inventory.sh from answering wrongly on bad input

Six ways the selector could hand a caller the wrong host list, all of them
silent, which is the failure mode the script exists to prevent:

- `--tag ""` matched nothing, so the filter was dropped and the ENTIRE fleet
  came back at exit 0. An unset `$DEVNET` in `--tag "$DEVNET"` would act on
  hosts on other chains, the mirror image of the typo case already guarded.
- The unknown-argument path printed help to stdout, and the documented idiom
  captures stdout: a mistyped flag fed 1.4 KB of usage text into a host loop.
- `--not-tag T` hard-failed when no host carried T, contradicting the script's
  own `--tag validator` == `--tag <devnet> --not-tag aggregator` equivalence.
  An exclusion matching nothing is well-defined; only `--tag` is checked now.
- Nothing validated nodes/subnets, so one space in the tags column shifted every
  later field: a role landed in `nodes`, `--tag validator` returned the
  aggregator, and a word reached a caller expecting a count. The file is now
  refused with the row named, rather than answered from.
- Tag arguments were glob-expanded against the cwd, so `--tag 'devnet-*'` could
  silently resolve to a different group than typed.
- `usage()` sliced help from a hardcoded line range; it now ends at the first
  non-comment line, so editing the header cannot truncate `--help`.

The documented recipes were also unrunnable as written: `inventory.sh` is not on
PATH, and the `| tr` pipeline discarded the exit code the script sets so
carefully, turning any error into an empty-but-successful host list.

Author: MegaRedHand

.claude/skills/multi-server-devnet/SKILL.md

@@ -58,18 +58,20 @@ file. It is the one place a deployment's urls and Grafana ids live.
 than reading it by hand:
 
 ```bash
-inventory.sh --tag devnet-ab --field ip        # ips, one per line, for a loop
-inventory.sh --tag devnet-ab --tag aggregator  # AND across tags
-inventory.sh --tag validator                   # derived, see below
-SERVERS=$(inventory.sh --field name | tr '\n' ' ')
+bash scripts/inventory.sh --tag devnet-ab --field ip        # ips, for a loop
+bash scripts/inventory.sh --tag devnet-ab --tag aggregator  # AND across tags
+bash scripts/inventory.sh --tag validator                   # derived, see below
+SERVERS=$(bash scripts/inventory.sh --field name) || exit   # exit 2 = typo'd tag
+SERVERS=${SERVERS//$'\n'/ }                                 # newlines -> spaces
 ```
 
 Tag conventions: a `devnet-*` tag names the chain a host's nodes belong to (two
 hosts sharing one means the split-chain model, *not* two like-named devnets), and
 `aggregator` is a whole-server role. `validator` is **derived** — "has a `devnet-*`
 tag and is not tagged `aggregator`" — so it can never disagree with the aggregator
-tag. An unknown tag exits 2 with the known-tag list rather than returning nothing,
-because a typo that yields an empty loop reports success while doing nothing.
+tag. An unknown or empty `--tag` exits 2 rather than returning nothing (or, worse,
+everything): a typo that yields an empty loop reports success while doing nothing,
+and `--tag "$UNSET"` would act on hosts the caller never named.
 
 `NODES`/`SUBNETS` there are still the operator's inventory: the scripts take them
 as positional args, and the authority on a running devnet is always its own

.claude/skills/multi-server-devnet/scripts/devnet.inventory.example

@@ -9,10 +9,11 @@
 #
 # Read it with inventory.sh rather than by hand:
 #
-#   inventory.sh --tag devnet-ab --field ip        # ips, one per line, for a loop
-#   inventory.sh --tag devnet-ab --tag aggregator  # AND: both tags must be present
-#   inventory.sh --tag validator                   # derived, see TAGS below
-#   SERVERS=$(inventory.sh --field name | tr '\n' ' ')
+#   bash scripts/inventory.sh --tag devnet-ab --field ip        # ips, for a loop
+#   bash scripts/inventory.sh --tag devnet-ab --tag aggregator  # AND: both needed
+#   bash scripts/inventory.sh --tag validator                   # derived, see TAGS
+#   SERVERS=$(bash scripts/inventory.sh --field name) || exit   # exit 2 = typo'd tag
+#   SERVERS=${SERVERS//$'\n'/ }                                 # newlines -> spaces
 #
 # FORMAT — whitespace-separated columns, aligned however you like. Blank lines and
 # lines whose first non-space character is '#' are ignored. Five columns:
@@ -22,7 +23,8 @@
 #             resolves it, so a stale name here misroutes every ssh that uses it.
 #   ip        address. The one field worth re-deriving from the fleet rather than
 #             trusting after a rebuild.
-#   tags      COMMA-separated, NO spaces (a space would start the next column).
+#   tags      COMMA-separated, NO spaces (a space would start the next column;
+#             inventory.sh rejects the file rather than answer from shifted rows).
 #   nodes     NODES on this server, or '-' if it runs no devnet.
 #   subnets   ATTESTATION_COMMITTEE_COUNT, or '-'.
 #

.claude/skills/multi-server-devnet/scripts/inventory.sh

@@ -18,15 +18,44 @@
 # It is computed, not read, so it can never disagree with the aggregator tag.
 # `--tag validator` is exactly `--tag <that devnet> --not-tag aggregator`.
 #
-# An unknown tag is an ERROR, not an empty result. A typo ('devnet5' for
+# An unknown `--tag` is an ERROR, not an empty result. A typo ('devnet5' for
 # 'devnet-5') that quietly returns no hosts turns `for h in $(inventory.sh ...)`
 # into a loop that does nothing and reports success, which is the same class of
 # failure devnet-env.sh guards against: acting on the wrong deployment, silently.
-# A tag that IS known but matches nothing is likewise exit 1 -- a real fleet has
-# no empty groups, so an empty match means the inventory is stale.
+# An EMPTY --tag value is an error for the mirror-image reason: an unset variable
+# in `--tag "$DEVNET"` would drop the filter and return the whole fleet, exit 0,
+# including hosts on other chains. A tag that IS known but matches nothing is
+# exit 1 -- a real fleet has no empty groups, so that means a stale inventory.
+#
+# `--not-tag` is deliberately NOT checked against the file: an exclusion that
+# matches nothing is well-defined, and demanding the tag exist would break the
+# documented `--tag <devnet> --not-tag aggregator` on any fleet whose aggregator
+# role is currently unassigned.
 set -u
 
-usage() { sed -n '2,26p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; }
+# Sliced from the header block above, ending at the first non-comment line, so
+# editing the comment can't silently truncate --help.
+help_text() { awk 'NR == 1 { next } !/^#/ { exit } { sub(/^# ?/, ""); print }' "$0"; }
+
+# Help goes to stdout for -h, but to stderr on the error path: callers capture
+# this script's stdout ($(inventory.sh --field name)), so help text printed there
+# becomes a list of "hosts" to ssh into.
+usage() {
+  code=${1:-0}
+  if [ "$code" = 0 ]; then help_text; else help_text >&2; fi
+  exit "$code"
+}
+
+# Whitespace-split a tag argument into SPLIT with globbing OFF: a tag is data, and
+# `--tag 'devnet-*'` must not expand against whatever happens to sit in the cwd.
+split_tags() {
+  case $2 in
+    *[![:space:]]*) ;;
+    *) echo "$1 needs a non-empty value (an empty tag would match every host)" >&2
+       exit 2 ;;
+  esac
+  set -f; SPLIT=($2); set +f
+}
 
 file=""; field="default"; count=0
 tags=(); nottags=()
@@ -35,9 +64,9 @@ while [ $# -gt 0 ]; do
   case $1 in
     --tag)     [ $# -ge 2 ] || { echo "$1 needs a value" >&2; exit 2; }
                # Split on whitespace so --tag 'devnet-5 aggregator' is two tags.
-               for t in $2; do tags+=("$t"); done; shift 2 ;;
+               split_tags "$1" "$2"; tags+=("${SPLIT[@]}"); shift 2 ;;
     --not-tag) [ $# -ge 2 ] || { echo "$1 needs a value" >&2; exit 2; }
-               for t in $2; do nottags+=("$t"); done; shift 2 ;;
+               split_tags "$1" "$2"; nottags+=("${SPLIT[@]}"); shift 2 ;;
     --field)   [ $# -ge 2 ] || { echo "$1 needs a value" >&2; exit 2; }
                field=$2; shift 2 ;;
     --file)    [ $# -ge 2 ] || { echo "$1 needs a value" >&2; exit 2; }
@@ -95,6 +124,17 @@ awk -v want="${tags[*]-}" -v nowant="${nottags[*]-}" \
     name = $1; ip = $2; tags = $3
     nodes   = (NF >= 4 ? $4 : "-")
     subnets = (NF >= 5 ? $5 : "-")
+
+    # A space inside the tags column (or a trailing comment on a data row) shifts
+    # every later field: $3 loses tags, and a ROLE lands in nodes. Unlike a short
+    # row, which only drops one host, that silently reassigns roles and hands a
+    # word to a caller expecting a count -- so refuse the whole file instead.
+    if (nodes !~ /^([0-9]+|-)$/ || subnets !~ /^([0-9]+|-)$/) {
+      printf "%s:%d: nodes/subnets must be a number or '\''-'\'', got '\''%s'\'' '\''%s'\''", \
+        src, FNR, nodes, subnets > "/dev/stderr"
+      printf " -- a space in the tags column shifts the columns right\n" > "/dev/stderr"
+      malformed = 1; next
+    }
     t = "," tags ","
 
     # Every literal tag in the file, so a typo can be told from a real absence.
@@ -113,15 +153,18 @@ awk -v want="${tags[*]-}" -v nowant="${nottags[*]-}" \
   }
 
   END {
+    # Answering from a file whose columns do not line up would mean answering
+    # about tags that were never written; the row numbers are already on stderr.
+    if (malformed) {
+      printf "%s: refusing to answer from a file that does not parse\n", src > "/dev/stderr"
+      exit 2
+    }
+
     bad = 0
     for (i = 1; i <= nw; i++)
       if (W[i] != "validator" && !(W[i] in seen)) {
         printf "no such tag in %s: %s\n", src, W[i] > "/dev/stderr"; bad = 1
       }
-    for (i = 1; i <= nn; i++)
-      if (NW[i] != "validator" && !(NW[i] in seen)) {
-        printf "no such tag in %s: %s\n", src, NW[i] > "/dev/stderr"; bad = 1
-      }
     if (bad) {
       printf "known tags: " > "/dev/stderr"
       for (k in seen) printf "%s ", k > "/dev/stderr"