feat(tools/git): explain tea's misleading user does not exist error

`user does not exist [uid: 0, name: ]` from tea reads as a missing account. It almost always means a revoked or stale token: `tea login` keeps its own copy of the token, so rotating the credential store does not update it. The error points at the account; the cause is the cached credential. Adds explain_tea_user_does_not_exist() to detect-platform.sh and invokes it from the three tea-failure fallback paths, each guarded by `declare -F` so the call site is independent of load order and a no-op if the helper is absent. Purely additive: stderr only, no control flow, no gate or credential changes. Verified both directions: the helper emits when sourced, and the guarded call is a silent no-op (exit 1, no output) when it is not. Refs #1082 Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Amf1Neca162odgcbCWMk1y
2026-08-06 15:39:33 -05:00
4 changed files with 18 additions and 0 deletions
@@ -240,6 +240,21 @@ PY
    } >&2
 }

+# Explain tea's most misleading failure. `user does not exist [uid: 0, name: ]` reads
+# as a missing account; it almost always means a REVOKED OR STALE TOKEN. `tea login`
+# keeps its OWN COPY of the token, so rotating the credential store does not update it.
+# Diagnostic only -- stderr, no control flow, no exit.
+explain_tea_user_does_not_exist() {
+    cat >&2 <<'MSG'
+NOTE: `user does not exist [uid: 0, name: ]` from tea usually means a REVOKED OR STALE TOKEN,
+      not a missing account. A `tea login` stores its OWN COPY of the token; rotating the
+      credential store does NOT update it.
+      CHECK: the login's cached copy (`tea login list` -- read the FULL table, never `| head`),
+             then re-register that login against the current token.
+      DO NOT probe capability with a mutating request; a POST is the action, not a check.
+MSG
+}
+
 get_gitea_login_for_host() {
    local host="${1:-}"
    local login
@@ -156,6 +156,7 @@ case "$PLATFORM" in
                exit 0
            fi
            echo "Warning: tea issue create failed, trying Gitea API fallback..." >&2
+            declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist
        fi
        gitea_issue_create_api
        ;;
@@ -71,6 +71,7 @@ elif [[ "$PLATFORM" == "gitea" ]]; then
            exit 0
        fi
        echo "Warning: tea issue view failed, trying Gitea API fallback..." >&2
+        declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist
    fi
    gitea_issue_view_api
 else
@@ -219,6 +219,7 @@ case "$PLATFORM" in
            exit 0
        fi
        echo "Warning: tea pr create failed, trying Gitea API fallback..." >&2
+        declare -F explain_tea_user_does_not_exist >/dev/null && explain_tea_user_does_not_exist
        gitea_pr_create_api
        ;;
    *)