fix: narrow license-return retry classification

dist/platforms/mac/steps/return_license.sh

@@ -25,7 +25,13 @@ RETURN_STRATEGY="$(resolve_unity_license_return_strategy)"
 # a genuinely leaked seat needs a human to know about it (nothing here can
 # force Unity's server to release a seat it thinks is still in use).
 UNITY_LICENSE_RETURN_MAX_ATTEMPTS="${UNITY_LICENSE_RETRY_MAX_ATTEMPTS:-5}"
-UNITY_LICENSE_RETURN_TRANSIENT_PATTERN='TimeoutPolicy did not complete|Access token is unavailable|entitlement groups and 0 free entitlements|License activation has failed|No valid Unity Editor license found|License is not active|Serial number unavailable'
+# A return is not an activation.  The activation/build pattern deliberately
+# accepts state/authentication messages because a new attempt can establish a
+# licence.  On return, the same messages have been observed after a successful
+# return and beside permanent failures, so retrying them only delays cleanup and
+# can claim a seat is leaked when it was not.  TimeoutPolicy is the one explicit
+# transport timeout for which a later attempt can plausibly help.
+UNITY_LICENSE_RETURN_TRANSIENT_PATTERN='TimeoutPolicy did not complete'
 
 # Permanent by construction - see the guards below.
 UNITY_LICENSE_RETURN_PERMANENT_PATTERN="Machine bindings don't match"

dist/platforms/ubuntu/steps/return_license.sh

@@ -25,7 +25,13 @@ RETURN_STRATEGY="$(resolve_unity_license_return_strategy)"
 # mac/steps/build.sh) and, critically, logs loudly if every attempt is
 # exhausted, since a genuinely leaked seat needs a human to know about it.
 UNITY_LICENSE_RETURN_MAX_ATTEMPTS="${UNITY_LICENSE_RETRY_MAX_ATTEMPTS:-5}"
-UNITY_LICENSE_RETURN_TRANSIENT_PATTERN='TimeoutPolicy did not complete|Access token is unavailable|entitlement groups and 0 free entitlements|License activation has failed|No valid Unity Editor license found|License is not active|Serial number unavailable'
+# A return is not an activation.  The activation/build pattern deliberately
+# accepts state/authentication messages because a new attempt can establish a
+# licence.  On return, the same messages have been observed after a successful
+# return and beside permanent failures, so retrying them only delays cleanup and
+# can claim a seat is leaked when it was not.  TimeoutPolicy is the one explicit
+# transport timeout for which a later attempt can plausibly help.
+UNITY_LICENSE_RETURN_TRANSIENT_PATTERN='TimeoutPolicy did not complete'
 
 # Permanent by construction - see the guards below.
 UNITY_LICENSE_RETURN_PERMANENT_PATTERN="Machine bindings don't match"

dist/platforms/windows/return_license.ps1

@@ -30,7 +30,13 @@ $LicensingClientPath = "$Env:UNITY_PATH\Editor\Data\Resources\Licensing\Client\U
 # about it (nothing here can force Unity's server to release a seat it
 # thinks is still in use).
 $MaxAttempts = if ($Env:UNITY_LICENSE_RETRY_MAX_ATTEMPTS) { [int]$Env:UNITY_LICENSE_RETRY_MAX_ATTEMPTS } else { 5 }
-$TransientPattern = 'TimeoutPolicy did not complete|Access token is unavailable|entitlement groups and 0 free entitlements|License activation has failed|No valid Unity Editor license found|License is not active|Serial number unavailable'
+# A return is not an activation. The activation/build pattern deliberately
+# accepts state/authentication messages because a new attempt can establish a
+# licence. On return, the same messages have been observed after a successful
+# return and beside permanent failures, so retrying them only delays cleanup and
+# can claim a seat is leaked when it was not. TimeoutPolicy is the one explicit
+# transport timeout for which a later attempt can plausibly help.
+$TransientPattern = 'TimeoutPolicy did not complete'
 
 # Permanent by construction: the entitlement is bound to the machine that
 # activated it, so no retry rebinds it. Checked separately because the same
@@ -208,4 +214,4 @@ elseif ($ReturnStrategy -eq 'serial') {
   }
 }
 
-Pop-Location
+Pop-Location

dist/platforms/windows/steps/return_license.ps1

@@ -23,7 +23,13 @@ $ReturnStrategy = Get-UnityLicenseReturnStrategy
 # mac/steps/return_license.sh and the host-mode windows/return_license.ps1
 # already pass).
 $MaxAttempts = if ($Env:UNITY_LICENSE_RETRY_MAX_ATTEMPTS) { [int]$Env:UNITY_LICENSE_RETRY_MAX_ATTEMPTS } else { 5 }
-$TransientPattern = 'TimeoutPolicy did not complete|Access token is unavailable|entitlement groups and 0 free entitlements|License activation has failed|No valid Unity Editor license found|License is not active|Serial number unavailable'
+# A return is not an activation. The activation/build pattern deliberately
+# accepts state/authentication messages because a new attempt can establish a
+# licence. On return, the same messages have been observed after a successful
+# return and beside permanent failures, so retrying them only delays cleanup and
+# can claim a seat is leaked when it was not. TimeoutPolicy is the one explicit
+# transport timeout for which a later attempt can plausibly help.
+$TransientPattern = 'TimeoutPolicy did not complete'
 
 # Permanent by construction: the entitlement is bound to the machine that
 # activated it, so no retry rebinds it. Checked separately because the same

scripts/test-licensing-steps.sh

@@ -678,6 +678,27 @@ check "and names the real cause instead of implying a leaked seat" "$OUT" \
   "bound to a different machine"
 refute "and does not send the user hunting a leak" "$OUT" "may still be held"
 
+# Return must not inherit activation's broad error classifier.  Unity emits an
+# unavailable access token both after a successful return and beside permanent
+# failures; without a success line it is ambiguous, not evidence that waiting
+# will make a second return possible.
+cat > "$WORK/unity-editor" <<'STUB'
+#!/usr/bin/env bash
+echo "EDITOR $*" >> "$ARGV_LOG"
+echo "[Licensing::Module] Error: Access token is unavailable; failed to update"
+echo "[Licensing::Module] Error: Failed to return entitlement license"
+exit 1
+STUB
+chmod +x "$WORK/unity-editor"
+
+: > "$ARGV_LOG"
+OUT=$(run_step UNITY_EMAIL="ci@example.com" UNITY_PASSWORD="pw123456" UNITY_SERIAL="F4-XXXX-XXXX-XXXX-XXXX-XXXX" \
+  UNITY_LICENSE_RETRY_MAX_ATTEMPTS=4 UNITY_LICENSE_RETRY_DELAY_SECONDS=0 \
+  bash -c 'source "$STEPS_DIR/return_license.sh"' 2>&1)
+refute "does not retry an ambiguous access-token message on return" "$OUT" \
+  "known-transient Unity licensing error"
+check "and only attempts the return once" "$(grep -c '^EDITOR' "$ARGV_LOG")" "1"
+
 # The return has to use the same route the activation used. activate.sh falls
 # back to the editor when the bundled client predates --include-personal
 # (2020.3.49f1 ships 1.12.1), and that route takes an *entitlement* seat - no