fix(admin/sqs): map leader-churn errors to 503; add tests; SPA polish

Three findings from Claude review on PR #670:

1. (P1) translateAdminQueuesError did not catch leader-churn errors.
   AdminDeleteQueue passes the upfront isVerifiedSQSLeader check,
   then dispatches deleteQueueWithRetry which can hit a kv coordinator
   that just lost leadership. The resulting kv.ErrLeaderNotFound /
   adapter.ErrNotLeader / wrapped "not leader" suffixes were not in
   the translator's switch — they fell to default and the admin
   handler rendered a generic 500 instead of the spec'd 503 +
   Retry-After: 1. Added the `case isLeaderChurnError(err)` arm
   mirroring translateAdminTablesError's identical fix from PR #634.

2. (P2) No tests for translateAdminQueuesError. Mirrored the three
   Dynamo equivalents in main_admin_test.go:
     - TestTranslateAdminQueuesError_LeaderChurn covers every kv
       sentinel + canonical wrapped-suffix variant.
     - TestTranslateAdminQueuesError_LeaderPhraseInMiddleOfMessage
       pins the HasSuffix matcher behaviour against false positives
       on user-supplied error messages mid-string.
     - TestTranslateAdminQueuesError_UnrelatedErrorPassesThrough
       confirms the detector does not swallow innocent "leader"
       mentions outside the canonical phrase set.

3. (Low / polish) SqsList.tsx subtitle leaked the Go file path
   "adapter/sqs_admin.go" and the internal milestone name
   "Phase 3.A" to end users — DynamoList / S3List don't do this.
   Replaced with operator-facing prose describing what the page does.

Verified:
  - go test -run TestTranslateAdminQueuesError . — passes
  - go build ./... clean
  - go test -race ./internal/admin/... + go test -race -run TestSQS ./adapter/ — pass
  - golangci-lint run ./adapter/... ./internal/admin/... ./... — 0 issues
  - cd web/admin && npm run lint (tsc --strict) clean

Author: bootjp

main_admin.go

@@ -211,8 +211,21 @@ func translateAdminQueuesError(err error) error {
 		return admin.ErrQueuesNotFound
 	case errors.Is(err, adapter.ErrAdminSQSValidation):
 		return admin.ErrQueuesValidation
+	case isLeaderChurnError(err):
+		// Leadership can be lost between AdminDeleteQueue's upfront
+		// isVerifiedSQSLeader check and the coordinator dispatch
+		// inside deleteQueueWithRetry. The kv coordinator surfaces
+		// that as ErrLeaderNotFound / ErrNotLeader (or a wrapped
+		// "not leader" / "leader not found" suffix), and the
+		// retry loop's isRetryableTransactWriteError does not catch
+		// them. Without this arm the error falls to default and the
+		// admin handler renders a generic 500 — Codex P2 + Claude
+		// P1 on PR #670 confirmed the gap. Mirrors the same arm in
+		// translateAdminTablesError that fixed this for Dynamo on
+		// PR #634.
+		return admin.ErrQueuesNotLeader
 	default:
-		return err
+		return err //nolint:wrapcheck // forwarded so the handler logs but does not surface it.
 	}
 }
 

main_admin_test.go

@@ -426,3 +426,63 @@ func TestTranslateAdminTablesError_UnrelatedErrorPassesThrough(t *testing.T) {
 	require.NotErrorIs(t, out, admin.ErrTablesNotLeader)
 	require.Equal(t, in, out)
 }
+
+// TestTranslateAdminQueuesError_LeaderChurn is the SQS counterpart of
+// TestTranslateAdminTablesError_LeaderChurn. AdminDeleteQueue clears
+// the upfront isVerifiedSQSLeader check but the kv coordinator can
+// still drop leadership inside deleteQueueWithRetry's Dispatch; the
+// resulting ErrLeaderNotFound / ErrNotLeader / wrapped suffixes must
+// classify as 503 leader_unavailable, not the generic 500 fallthrough.
+// Codex P2 + Claude P1 on PR #670 confirmed the original gap.
+func TestTranslateAdminQueuesError_LeaderChurn(t *testing.T) {
+	cases := []struct {
+		name string
+		in   error
+	}{
+		{"kv.ErrLeaderNotFound", kv.ErrLeaderNotFound},
+		{"adapter.ErrNotLeader", adapter.ErrNotLeader},
+		{"adapter.ErrLeaderNotFound", adapter.ErrLeaderNotFound},
+		{"wrapped not leader", errors.New("dispatch failed: not leader")},
+		{"wrapped leader not found", errors.New("dispatch: leader not found")},
+		{"wrapped leadership lost", errors.New("commit aborted: leadership lost")},
+		{"wrapped leadership transfer", errors.New("retry exhausted: leadership transfer in progress")},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			out := translateAdminQueuesError(tc.in)
+			require.ErrorIs(t, out, admin.ErrQueuesNotLeader,
+				"input %q must map to ErrQueuesNotLeader", tc.in)
+		})
+	}
+}
+
+// TestTranslateAdminQueuesError_LeaderPhraseInMiddleOfMessage is the
+// SQS counterpart of the same Tables test — pins that the HasSuffix
+// matcher in isLeaderChurnError does not false-positive on
+// user-supplied error messages that happen to mention a leader
+// phrase mid-string (e.g. a queue name or attribute value that
+// happens to contain "not leader").
+func TestTranslateAdminQueuesError_LeaderPhraseInMiddleOfMessage(t *testing.T) {
+	cases := []string{
+		"not leader: actually a downstream error",
+		"leader not found, but recovered automatically",
+		"leadership lost mid-snapshot, retried successfully",
+	}
+	for _, msg := range cases {
+		t.Run(msg, func(t *testing.T) {
+			out := translateAdminQueuesError(errors.New(msg))
+			require.NotErrorIs(t, out, admin.ErrQueuesNotLeader,
+				"mid-message leader phrase %q must not classify as leader-churn", msg)
+		})
+	}
+}
+
+// TestTranslateAdminQueuesError_UnrelatedErrorPassesThrough confirms
+// the leader-churn detector does not swallow unrelated errors that
+// happen to mention the word "leader" outside the canonical phrases.
+func TestTranslateAdminQueuesError_UnrelatedErrorPassesThrough(t *testing.T) {
+	in := errors.New("team leader misconfigured")
+	out := translateAdminQueuesError(in)
+	require.NotErrorIs(t, out, admin.ErrQueuesNotLeader)
+	require.Equal(t, in, out)
+}

web/admin/src/pages/SqsList.tsx

@@ -11,9 +11,8 @@ export function SqsListPage() {
         <div>
           <h1 className="text-xl font-semibold">SQS queues</h1>
           <p className="text-xs text-muted">
-            Backed by the SigV4-bypass admin entrypoints in
-            <code className="font-mono ml-1">adapter/sqs_admin.go</code>.
-            Detail pages show the new approximate counters from Phase 3.A.
+            List, describe, and delete SQS queues. Detail pages also surface
+            the approximate visible / in-flight / delayed message counts.
           </p>
         </div>
         <button type="button" className="btn-secondary" onClick={queues.reload}>