claude-multiacc 1.0.15 → 1.0.17

package/README.md

@@ -435,6 +435,26 @@ Use `--token` when you specifically want one account usable on the server via th
 sync (the ~1-year inference-only token that mirrors over). For everyday adds, the default
 full login is smoother. `status` warns when a token nears end of life; re-run `login`.
 
+### A setup token has no identity — name the account yourself
+
+A setup token is minted with scope `user:inference` **alone**, so `claude auth status`
+answers `{loggedIn, authMethod, apiProvider}` and no email — only an OAuth login reports
+`email`/`orgId`/`subscriptionType`. Nothing on this side can therefore learn which account
+approved a `setup-token` grant, and no future check will change that.
+
+What follows, and what the CLI does about it:
+
+- **`add <email> --token` requires the email** — there is nothing to read the account back
+  from. It registers under the name you gave and says so; naming no email is refused
+  outright rather than registering an anonymous slot.
+- **`mint <acct-NN>` names the account in its prompt** (`approve in a browser signed in as
+  …`) and warns afterwards that the identity is unverifiable. Approving in a window signed
+  into a *different* account silently binds that account's subscription to the slot —
+  every machine then runs it under the wrong name. Sign in to the right account **first**,
+  in a fresh private window, then paste the link.
+- `login <acct-NN> --token` compares against the manifest when an identity is readable
+  (it is not, today) and otherwise says what it is trusting.
+
 Both accounts currently in the pool are live and verified: acct-01 (support@gowalkae.com,
 Mac) and acct-02 (hasan@gowalkqa.com, server) — each adopted from its machine's existing
 login, so each runs on the machine that holds its credential.

package/bin/claude

@@ -475,6 +475,48 @@ client_limit_scan() { # $1 acct dir
   return 1
 }
 
+# A TUI auth failure cannot use the -p retry path because the client owns the terminal.
+# Harvest the same account-owned transcripts used for quota detection so the next launch
+# parks a rejected setup-token instead of selecting it again.
+client_auth_scan() { # $1 acct dir
+  local idx="$1/.sessions-index" ln id claim p line ts ck ak read_n=0 i
+  local ids=() claims=()
+  [ -f "$idx" ] || return 1
+  while IFS= read -r ln; do
+    id="${ln%% *}"; claim=""
+    case "$ln" in *' '*) claim="${ln#* }" ;; esac
+    sess_id_ok "$id" && { ids+=("$id"); claims+=("$claim"); }
+  done < "$idx"
+  i=$(( ${#ids[@]} - 1 ))
+  while [ "$i" -ge 0 ] && [ "$read_n" -lt "$QUOTA_SCAN_MAX_FILES" ]; do
+    id="${ids[$i]}"; claim="${claims[$i]}"; i=$((i - 1)); read_n=$((read_n + 1))
+    sess_transcript "$1" "$id" || continue
+    p="$SESS_TRANSCRIPT"
+    [ $((now - $(file_mtime "$p"))) -le "$QUOTA_SCAN_MAX_AGE" ] || continue
+    line="$(tail -c "$QUOTA_SCAN_BYTES" "$p" 2>/dev/null \
+      | LC_ALL=C grep -a '"error"[[:space:]]*:[[:space:]]*"authentication_failed"' | tail -1)"
+    [ -n "$line" ] || continue
+    [ -n "$claim" ] || continue
+    ts="$(printf '%s' "$line" | LC_ALL=C sed -n 's/.*"timestamp"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')"
+    ck="$(iso_key "$ts")"; ak="$(iso_key "$claim")"
+    num_ok "$ck" || continue; num_ok "$ak" || continue
+    [ "$ck" -lt "$ak" ] && continue
+    claim_conflicted "$1" "$id" "$claim" && continue
+    return 0
+  done
+  return 1
+}
+
+mark_client_auth_dead() { # $1 acct dir
+  local soft=$((now + 3600)) marked
+  marked="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  { echo "$now"; echo "reason=auth-error soft_until=$soft marked_at=$marked" \
+      "detail=client session failed to authenticate"; } \
+    2>/dev/null > "$1/.expired.$$" && mv -f "$1/.expired.$$" "$1/.expired" 2>/dev/null \
+    || rm -f "$1/.expired.$$" 2>/dev/null || true
+  sel_log "$(basename "$1") parked (auth-error until $soft) — client-reported"
+}
+
 mark_client_limit() { # $1 acct dir, $2 reset epoch, $3 rate limit type
   local m="$1/.limited" cur=""
   # Never shorten a marker that already reaches further out (a weekly park must
@@ -507,11 +549,11 @@ sel_capture_session() { # $1 acct dir
     # stops the moment the run it is watching is gone.
     trap '' INT HUP TERM QUIT
     i=0
-    while [ "$i" -lt 30 ]; do
+    while [ "$i" -lt 600 ]; do
       kill -0 "$pid" 2>/dev/null || break
       sess_index_refresh "$d"
       [ -f "$d/sessions/$pid.json" ] && break
-      sleep 2
+      sleep 0.1
       i=$((i + 1))
     done
     sess_index_refresh "$d"
@@ -638,6 +680,12 @@ for d in "$ACC_ROOT"/acct-*; do
   fi
   valid+=("$d")
   sess_index_refresh "$d"
+  if client_auth_scan "$d"; then
+    mark_client_auth_dead "$d"
+    valid=("${valid[@]:0:${#valid[@]}-1}")
+    expired+=("$d")
+    continue
+  fi
   marker_active "$d" && continue
   # The account's own records are consulted BEFORE telemetry: what the server told a real
   # call is first-hand and carries the real reset, while limits.json can be days stale —

package/bin/claude-accounts

@@ -461,6 +461,13 @@ cmd_add() {
       return 0
     fi
   fi
+  # A setup token reports no identity, so an unnamed --token add can never attribute the
+  # account. Refuse BEFORE the ceremony: running it first would mint a real 1-year grant
+  # on the account's behalf and then throw the token away, leaving a live credential
+  # issued for nothing.
+  if [ "$token" = "1" ] && [ -z "$email" ]; then
+    die "a setup token carries no identity, so the account cannot be read back — name it: claude-accounts add <email> --token"
+  fi
   if [ ! -t 0 ] && [ -z "${CLAUDE_MULTIACC_FORCE_TTY:-}" ]; then
     die "add is interactive (it completes sign-in before registering) — run it from a terminal"
   fi
@@ -498,7 +505,14 @@ cmd_add() {
     got="$(config_dir_email "$d")"
   fi
   if [ -z "$got" ]; then
-    if [ -n "$email" ] && [ "$force" = "1" ]; then
+    if [ "$token" = "1" ] && [ -n "$email" ]; then
+      # A setup token NEVER reports an identity (see token_email) — that is the grant's
+      # design, not a read that failed, so demanding --force here demanded a ceremony
+      # nobody can perform: it made the documented `add <email> --token` path die every
+      # single time. The named email is all there is; say so plainly and register it.
+      warn "a setup token carries no identity — registering as $email, the account you were asked to approve as"
+      got="$email"
+    elif [ -n "$email" ] && [ "$force" = "1" ]; then
       warn "identity unverified — registering as $email because --force was given"
       got="$email"
     else
@@ -523,10 +537,18 @@ cmd_add() {
   mutate_unlock
   RESERVED_DIR=""            # committed — the trap must not delete it now
   trap - EXIT INT TERM
-  log_to ops.log "add $id $got (auth-verified)"
+  # Only the full-login path actually READ the identity back. Saying "verified" for a
+  # setup token would relaunder the very assumption this flow just warned about.
+  local verdict="sign-in verified"
+  if [ "$token" = "1" ]; then
+    verdict="identity unverifiable — trusted as the name you gave"
+    log_to ops.log "add $id $got (token; identity unverifiable)"
+  else
+    log_to ops.log "add $id $got (auth-verified)"
+  fi
   auto_sync
   cat <<EOF
-Registered $id for $got (sign-in verified) — usable immediately.
+Registered $id for $got ($verdict) — usable immediately.
 Optional:
   claude-accounts verify       # confirm the 100% matrix
 EOF
@@ -783,7 +805,23 @@ TIP
   }
 }
 
-token_email() { # $1 = token; prints the authenticated email (best effort)
+account_email() { # $1 = acct id; prints the email the manifest holds for it
+  "$PYBIN" - "$MANIFEST" "$1" <<'PYEOF'
+import json, sys
+for a in json.load(open(sys.argv[1])).get('accounts', []):
+    if a['id'] == sys.argv[2]:
+        print(a.get('email', ''))
+        break
+PYEOF
+}
+
+token_email() { # $1 = token; prints the authenticated email — EMPTY for a setup token
+  # A setup token is minted with scope user:inference ALONE, so `claude auth status`
+  # answers {loggedIn, authMethod, apiProvider} and nothing else; an OAuth login also
+  # answers email/orgId/subscriptionType. There is therefore no way to learn which
+  # account approved a setup-token grant. Callers must read "" as "unknowable by
+  # design" — never as a transient failure worth retrying — and guard the ceremony by
+  # NAMING the expected account up front instead.
   local real
   real="$(find_real_claude "$_self")" || { echo ""; return 0; }
   CLAUDE_CODE_OAUTH_TOKEN="$1" CLAUDE_SHIM_ACTIVE=1 "$real" auth status 2>/dev/null | "$PYBIN" -c '
@@ -838,30 +876,55 @@ TIP
 }
 
 cmd_mint() {
+  # The minted token is the ONLY credential that reaches the server and every peer, so a
+  # mint under the wrong browser session hands this slot another account's subscription —
+  # and nothing downstream can notice (a setup token reports no identity, see
+  # token_email). Naming the expected account before the ceremony opens is the only guard
+  # that exists; the old prompt said "THIS account" and named nobody.
   require_manifest
-  local id="${1:-}" paste="${2:-}"
+  local id="" paste=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --paste) paste=1; shift ;;
+      --*) die "unknown option: $1" ;;
+      *) if [ -z "$id" ]; then id="$1"; shift
+         else die "unexpected argument: $1 (usage: claude-accounts mint <acct-NN> [--paste])"; fi ;;
+    esac
+  done
   [ -n "$id" ] || die "usage: claude-accounts mint <acct-NN> [--paste]"
   valid_acct_id "$id" || die "not a valid account id: $id"
+  # A bare directory is NOT enough: removed accounts and killed `add` runs leave acct-NN
+  # dirs behind (this Mac carries nine), and minting into one binds a live token to a slot
+  # the manifest cannot name — which is exactly the unattributable state this guards.
+  account_ids | grep -qx "$id" \
+    || die "unknown account: $id — mint binds a token to a REGISTERED account ('claude-accounts list' shows them)"
   local d="$ACC_ROOT/$id"
-  [ -d "$d" ] || die "unknown account dir: $d"
-  local tok=""
-  if [ "$paste" = "--paste" ]; then
-    printf 'Paste the sk-ant-oat... token: '
+  seed_account_dir "$d"
+  local email tok="" got
+  email="$(account_email "$id")"
+  [ -n "$email" ] || die "$id has no email in the manifest — refusing to mint a token nobody could attribute"
+  if [ "$paste" = "1" ]; then
+    printf 'Paste the sk-ant-oat... token for %s (%s): ' "$id" "${email:-unknown email}"
     read -r tok
     tok="$(printf '%s' "$tok" | tr -d '[:space:]')"
   else
-    echo "Running 'claude setup-token' for $id — approve in a browser signed into THIS account."
+    echo "Running 'claude setup-token' for $id — approve in a browser signed in as ${email:-THIS account}."
     run_token_ceremony "$d" || die "no token captured — mint failed"
     tok="$CEREMONY_TOKEN"
   fi
   [ -n "$tok" ] || die "no token captured — mint failed"
   valid_subscription_token "$tok" \
     || die "that is not a subscription setup-token (sk-ant-oat...). API keys are not supported."
+  got="$(token_email "$tok")"
+  if [ -n "$got" ] && [ -n "$email" ] && [ "$got" != "$email" ]; then
+    die "that token authenticates as $got but $id is $email — nothing saved"
+  fi
   ( umask 077; printf '%s' "$tok" > "$d/server.token" )
   chmod 600 "$d/server.token"
   clear_auth_markers "$d"
   log_to ops.log "mint $id"
   echo "Token saved to $d/server.token"
+  [ -n "$got" ] || warn "a setup token carries no identity — $id now runs whichever account approved that grant${email:+, trusted to be $email}"
   auto_sync
 }
 
@@ -884,14 +947,7 @@ cmd_login() {
   account_ids | grep -qx "$id" || die "unknown account: $id"
   local d="$ACC_ROOT/$id" email got
   seed_account_dir "$d"
-  email="$("$PYBIN" - "$MANIFEST" "$id" <<'PYEOF'
-import json, sys
-for a in json.load(open(sys.argv[1])).get('accounts', []):
-    if a['id'] == sys.argv[2]:
-        print(a.get('email', ''))
-        break
-PYEOF
-)"
+  email="$(account_email "$id")"
   echo "Sign in as $email for $id."
   if [ "$token" = "1" ]; then
     run_token_ceremony "$d" || die "sign-in failed or aborted — nothing changed"
@@ -902,6 +958,7 @@ PYEOF
     ( umask 077; printf '%s' "$CEREMONY_TOKEN" > "$d/server.token" )
     chmod 600 "$d/server.token"
     clear_auth_markers "$d"
+    [ -n "$got" ] || warn "a setup token carries no identity — $id is trusted to hold $email because that is who you approved as"
     echo "$id token saved (portable — works on Mac and server)."
   else
     run_login_ceremony "$d" "$email" \
@@ -2126,6 +2183,20 @@ cmd_health() {
   return $rc
 }
 
+# Every KNOWN subcommand answers `--help`/`-h` with the usage text and exit 0. This is not
+# a nicety: app-robot's runner probes for a verb with `<verb> --help` and reads a non-zero
+# exit as "this build predates the verb", which silently parked panel-to-Mac credential
+# distribution for as long as the arg loops rejected the flag. An UNKNOWN verb must still
+# FAIL, or the probe stops meaning what it says — so this list must hold exactly the verbs
+# the dispatcher below implements, and a test pins that both ways.
+_KNOWN_VERBS="list status add import export-credential export-cred import-credential import-cred adopt dedupe remove mint login expired relogin re-login sync verify limits post-sync health self-update"
+case " $_KNOWN_VERBS " in
+  *" ${1:-help} "*)
+    for _arg in "$@"; do
+      case "$_arg" in --help|-h) usage; exit 0 ;; esac
+    done ;;
+esac
+
 case "${1:-help}" in
   list) shift; cmd_list "$@" ;;
   status) shift; cmd_status "$@" ;;

package/bin/codex-accounts

@@ -1935,6 +1935,20 @@ PYEOF
   echo "codex account pool: $ACC_ROOT (manifest ready)"
 }
 
+# Every KNOWN subcommand answers `--help`/`-h` with the usage text and exit 0. This is not
+# a nicety: app-robot's runner probes for a verb with `<verb> --help` and reads a non-zero
+# exit as "this build predates the verb", which silently parked panel-to-Mac credential
+# distribution for as long as the arg loops rejected the flag. An UNKNOWN verb must still
+# FAIL, or the probe stops meaning what it says — so this list must hold exactly the verbs
+# the dispatcher below implements, and a test pins that both ways.
+_KNOWN_VERBS="list status add import export-credential export-cred import-credential import-cred adopt dedupe remove login expired relogin re-login sync verify limits post-sync health self-update init-pool"
+case " $_KNOWN_VERBS " in
+  *" ${1:-help} "*)
+    for _arg in "$@"; do
+      case "$_arg" in --help|-h) usage; exit 0 ;; esac
+    done ;;
+esac
+
 case "${1:-help}" in
   list) shift; cmd_list "$@" ;;
   status) shift; cmd_status "$@" ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multiacc",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Multi-account addon for Claude Code and OpenAI Codex CLI: every claude / claude -p and every codex / codex exec runs under a randomly-picked subscription account with the most usage headroom. Mirrors to a deploy server. No API keys.",
   "type": "module",
   "bin": {

package/tests/run-tests.sh

@@ -43,6 +43,14 @@ cat > "$FAKEBIN/claude" <<'EOF'
 # fake real claude for tests (not a multiacc shim)
 if [ "${1:-}" = "auth" ] && [ "${2:-}" = "status" ]; then
   if [ -n "${FAKE_AUTH_FAIL:-}" ]; then echo '{"loggedIn": false}'; exit 0; fi
+  # A setup token is minted with scope user:inference ALONE, so the real CLI answers
+  # {loggedIn, authMethod, apiProvider} and NO email — only an OAuth login (config dir)
+  # reports one. The fake used to hand an email to both, which is precisely why every
+  # --token identity path passed here and died in the field.
+  if [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ] && [ -z "${CLAUDE_CONFIG_DIR:-}" ]; then
+    echo '{"loggedIn": true, "authMethod": "oauth_token", "apiProvider": "firstParty"}'
+    exit 0
+  fi
   printf '{"loggedIn": true, "email": "%s"}\n' "${FAKE_EMAIL:-fake@test}"
   exit 0
 fi
@@ -383,6 +391,24 @@ grep -q "all-expired: falling back" "$ACC/selection.log" \
 printf '%s' "$HEALTHY_CREDS" > "$ACC/acct-01/.credentials.json"
 printf '%s' "$HEALTHY_CREDS" > "$ACC/acct-02/.credentials.json"
 
+# A short interactive TUI can report auth failure and exit before the -p retry path can
+# inspect stderr. Its account-owned transcript must park that setup-token on the next run.
+auth_sid="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
+mkdir -p "$ACC/acct-01/projects/auth-regression"
+printf '%s %s\n' "$auth_sid" '2020-01-01T00:00:00Z' > "$ACC/acct-01/.sessions-index"
+auth_line='{"timestamp":"2026-08-22T20:27:29.985Z","error":"authentication_failed",'
+auth_line="$auth_line\"session_id\":\"$auth_sid\"}"
+printf '%s\n' "$auth_line" \
+  > "$ACC/acct-01/projects/auth-regression/$auth_sid.jsonl"
+out="$(claude 2>&1)"
+check "TUI transcript auth failure excludes rejected account" "CFG=acct-02" "$out"
+grep -q 'reason=auth-error' "$ACC/acct-01/.expired" 2>/dev/null \
+  && t_ok "TUI transcript auth failure writes .expired" \
+  || t_fail "TUI transcript auth marker" "no auth-error marker"
+rm -f "$ACC/acct-01/.expired" "$ACC/acct-01/.sessions-index" \
+  "$ACC/acct-01/projects/auth-regression/$auth_sid.jsonl"
+rmdir "$ACC/acct-01/projects/auth-regression" 2>/dev/null || true
+
 # ---- 9d. the .expired marker: excludes, and self-heals on a newer credential ----
 printf '%s\nreason=auth-error marked_at=now detail=test\n' "$now" > "$ACC/acct-01/.expired"
 touch -t 202001010101 "$ACC/acct-01/.credentials.json"   # credential OLDER than the marker
@@ -984,6 +1010,16 @@ claude-accounts remove acct-04 --yes >/dev/null 2>&1
 # ---- 15c1. add --token: portable setup-token instead of creds ------------------------
 out="$(CLAUDE_MULTIACC_FORCE_TTY=1 FAKE_EMAIL=tok@test claude-accounts add tok@test --token 2>&1)"
 check "add --token registers via portable token" "Registered acct-04 for tok@test" "$out"
+check "add --token says the identity cannot be verified" "a setup token carries no identity" "$out"
+case "$out" in
+  *"sign-in verified"*) t_fail "add --token must not claim a verified sign-in" "it says 'sign-in verified' for an identity nothing can read" ;;
+  *) t_ok "add --token does not claim a verified sign-in" ;;
+esac
+case "$(grep 'add acct-04 tok@test' "$ACC/ops.log" 2>/dev/null)" in
+  *auth-verified*) t_fail "ops.log must not record --token as auth-verified" "the audit trail would relaunder the assumption" ;;
+  *"identity unverifiable"*) t_ok "ops.log records the --token add as unverifiable" ;;
+  *) t_fail "ops.log line for the --token add" "not found" ;;
+esac
 [ -s "$ACC/acct-04/server.token" ] && t_ok "add --token writes server.token" || t_fail "add --token" "missing"
 out="$(CLAUDE_ACCOUNT=acct-04 claude 2>&1)"
 check "token account exports CLAUDE_CODE_OAUTH_TOKEN" "TOK=sk-ant-oat01-FAKE" "$out"
@@ -3854,6 +3890,74 @@ assert any('manifest' in w for w in d['warnings']), d['warnings']
   && t_ok "limits --json still emits a document (with a warning) when the pool is broken" \
   || t_fail "limits --json on a broken pool" "no usable document"
 
+# ---- 46. a setup token has no identity: the --token paths must not pretend --------
+# Regression for two field failures on 2026-08-24: `add <email> --token` died every time
+# with "identity could not be read back" (it demanded --force for a ceremony that cannot
+# exist), and `mint` named no account at all — so approving in the wrong browser session
+# silently pinned another account's subscription to the slot, undetectably.
+out="$(CLAUDE_MULTIACC_FORCE_TTY=1 claude-accounts add --token 2>&1)"
+rc=$?
+check "add --token with no email refuses precisely" "name it: claude-accounts add <email> --token" "$out"
+[ "$rc" != "0" ] && t_ok "add --token with no email exits nonzero" || t_fail "add --token no email" "exited 0"
+[ ! -d "$ACC/acct-04" ] && t_ok "refused --token add leaves no dir behind" || t_fail "add --token cleanup" "dir left"
+# ...and it must refuse BEFORE the ceremony: minting a real 1-year grant only to discard
+# it would leave a live credential issued for nothing.
+case "$out" in
+  *"sign-in link"*) t_fail "add --token refuses before the ceremony" "setup-token already ran for an account it cannot name" ;;
+  *) t_ok "add --token with no email never opens the ceremony" ;;
+esac
+
+# mint must refuse a bare acct-NN directory the manifest does not know: removed accounts
+# and killed `add` runs leave those behind, and a token bound to one is unattributable.
+mkdir -p "$ACC/acct-77"
+out="$(printf 'sk-ant-oat01-ORPHANORPHANORPHANORPHANORPHANORPHAN\n' \
+  | claude-accounts mint acct-77 --paste 2>&1)"
+check "mint refuses an unregistered account dir" "unknown account: acct-77" "$out"
+[ ! -s "$ACC/acct-77/server.token" ] && t_ok "no token is written into an orphan dir" \
+  || t_fail "mint orphan dir" "server.token was written to an unregistered slot"
+rm -rf "$ACC/acct-77"
+
+# mint must NAME the account it is about to bind a token to (the only guard there is).
+printf 'sk-ant-oat01-MINTNAMEDMINTNAMEDMINTNAMEDMINTNAMEDMINTNAMED\n' \
+  | claude-accounts mint acct-01 --paste > "$WORK/mint-named.out" 2>&1
+out="$(cat "$WORK/mint-named.out")"
+check "mint --paste names the account in its prompt" "for acct-01" "$out"
+check "mint warns that a setup token carries no identity" "carries no identity" "$out"
+
+# ---- 47. every known verb answers --help with exit 0 (app-robot probes with it) ----
+# app-robot's runner asks `<verb> --help` to decide whether a Mac's build has the verb;
+# a non-zero exit reads as "too old" and parked panel-to-Mac credential distribution.
+# _KNOWN_VERBS must hold EXACTLY what the dispatcher implements. A verb missing from it
+# hides a real verb from the probe; a verb listed but unimplemented makes --help answer 0
+# for something that does not exist, which is how the probe stops meaning anything. The
+# first cut of this gate got both wrong (mint listed in codex, init-pool in claude), so
+# the parity is checked from the source, both directions, for both binaries.
+for _bin in claude-accounts codex-accounts; do
+  _src="$REPO_DIR/bin/$_bin"
+  _dispatch="$(grep -oE '^  [a-z0-9|_-]+\) shift; cmd_' "$_src" | sed -e 's/) shift; cmd_//' -e 's/^  //' | tr '|\n' '  ')"
+  _gate="$(grep -m1 '^_KNOWN_VERBS=' "$_src" | sed -e 's/^_KNOWN_VERBS="//' -e 's/"$//')"
+  _parity=1
+  for _v in $_dispatch; do
+    case " $_gate " in
+      *" $_v "*) ;;
+      *) _parity=0; t_fail "$_bin: dispatcher has '$_v', _KNOWN_VERBS does not" "app-robot's probe would read the verb as absent" ;;
+    esac
+    "$_bin" "$_v" --help >/dev/null 2>&1
+    [ "$?" = "0" ] && t_ok "$_bin $_v --help exits 0" \
+      || t_fail "$_bin $_v --help" "non-zero exit — app-robot would read the verb as missing"
+  done
+  for _v in $_gate; do
+    case " $_dispatch " in
+      *" $_v "*) ;;
+      *) _parity=0; t_fail "$_bin: _KNOWN_VERBS lists '$_v', the dispatcher does not implement it" "--help would answer 0 for a verb that does not exist" ;;
+    esac
+  done
+  [ "$_parity" = "1" ] && t_ok "$_bin: the help gate and the dispatcher list the same verbs"
+  "$_bin" frobnicate --help >/dev/null 2>&1
+  [ "$?" != "0" ] && t_ok "$_bin: an UNKNOWN verb still fails --help (the probe keeps its meaning)" \
+    || t_fail "$_bin unknown verb --help" "exited 0 — the probe would accept a verb that does not exist"
+done
+
 # ---- summary ---------------------------------------------------------------------
 echo
 echo "passed: $PASS  failed: $FAIL"