feat(github): autopilot parity — typed RateLimitError/AuthError, GetOpenSubIssueNumbers, failed-retry labels, exported ParseParentIssueNumber (#77)

Gaps found while wiring Pilot M7 4d (autopilot cutover to the SDK client):
- doRequest now returns *RateLimitError on 429 AND header/message-classified
  403 rate limits (with parsed Retry-After/X-RateLimit-Reset), and *AuthError
  on 401 — hosts use errors.As on these (ported verbatim from the pre-
  extraction client). Retry layer gains typed fast paths (403-rate-limits are
  now correctly retryable; AuthError is not; RetryAfter honored without
  string parsing).
- GetOpenSubIssueNumbers: list-returning sibling of GetOpenSubIssueCount —
  hosts cross-check each open child, a count is insufficient.
- LabelPilot + pilot-failed-retry-* constants + FailedRetryStateLabels.
- ParseParentIssueNumber exported (delegates to the poller-internal parser).

sdk/core untouched; api.golden byte-identical.

Author: alekspetrov

sdk/integrations/github/client.go

@@ -203,7 +203,31 @@ func (c *Client) doRequest(ctx context.Context, method, path string, body interf
 		}
 
 		if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-			return fmt.Errorf("API error (status %d): %s", resp.StatusCode, string(respBody))
+			msg := string(respBody)
+			if resp.StatusCode == http.StatusUnauthorized {
+				return &AuthError{Message: msg}
+			}
+			if resp.StatusCode == http.StatusTooManyRequests {
+				return &RateLimitError{
+					StatusCode: http.StatusTooManyRequests,
+					RetryAfter: parseRetryAfterHeader(resp.Header),
+					Message:    msg,
+				}
+			}
+			if resp.StatusCode == http.StatusForbidden {
+				msgLower := strings.ToLower(msg)
+				isRateLimit := resp.Header.Get("X-RateLimit-Remaining") == "0" ||
+					strings.Contains(msgLower, "secondary rate limit") ||
+					strings.Contains(msgLower, "rate limit exceeded")
+				if isRateLimit {
+					return &RateLimitError{
+						StatusCode: http.StatusForbidden,
+						RetryAfter: parseRetryAfterHeader(resp.Header),
+						Message:    msg,
+					}
+				}
+			}
+			return fmt.Errorf("API error (status %d): %s", resp.StatusCode, msg)
 		}
 
 		if result != nil && len(respBody) > 0 {
@@ -1128,6 +1152,58 @@ func (c *Client) LinkSubIssue(ctx context.Context, owner, repo string, parentNum
 	return c.ExecuteGraphQL(ctx, mutation, variables, nil)
 }
 
+// GetOpenSubIssueNumbers queries native GitHub sub-issues for a parent issue
+// and returns the numbers of sub-issues in OPEN state plus whether the parent
+// has any native sub-issue links at all. Callers that need to cross-check each
+// open child individually (rather than just count them) use this variant.
+func (c *Client) GetOpenSubIssueNumbers(ctx context.Context, owner, repo string, parentNum int) (numbers []int, hasNativeLinks bool, err error) {
+	parentID, err := c.GetIssueNodeID(ctx, owner, repo, parentNum)
+	if err != nil {
+		return nil, false, fmt.Errorf("resolve parent node ID: %w", err)
+	}
+
+	const query = `query($issueID: ID!) {
+		node(id: $issueID) {
+			... on Issue {
+				subIssues(first: 100) {
+					totalCount
+					nodes {
+						number
+						state
+					}
+				}
+			}
+		}
+	}`
+
+	var result struct {
+		Node struct {
+			SubIssues struct {
+				TotalCount int `json:"totalCount"`
+				Nodes      []struct {
+					Number int    `json:"number"`
+					State  string `json:"state"`
+				} `json:"nodes"`
+			} `json:"subIssues"`
+		} `json:"node"`
+	}
+
+	if err := c.ExecuteGraphQL(ctx, query, map[string]interface{}{"issueID": parentID}, &result); err != nil {
+		return nil, false, fmt.Errorf("query sub-issues for %s/%s#%d: %w", owner, repo, parentNum, err)
+	}
+
+	if result.Node.SubIssues.TotalCount == 0 {
+		return nil, false, nil
+	}
+
+	for _, n := range result.Node.SubIssues.Nodes {
+		if n.State == "OPEN" {
+			numbers = append(numbers, n.Number)
+		}
+	}
+	return numbers, true, nil
+}
+
 // GetOpenSubIssueCount queries native GitHub sub-issues for a parent issue and returns:
 //   - count: number of sub-issues in OPEN state
 //   - hasNativeLinks: true when the parent has at least one native sub-issue link

sdk/integrations/github/errors.go

@@ -0,0 +1,51 @@
+package github
+
+import (
+	"fmt"
+	"net/http"
+	"strconv"
+	"time"
+)
+
+// RateLimitError is returned by doRequest when GitHub signals a rate limit via
+// a 403 or 429 response. It carries the parsed Retry-After duration so the
+// retry loop can honor it without regexing the error string.
+type RateLimitError struct {
+	StatusCode int
+	RetryAfter time.Duration
+	Message    string
+}
+
+func (e *RateLimitError) Error() string {
+	return fmt.Sprintf("API error (status %d): %s", e.StatusCode, e.Message)
+}
+
+// AuthError is returned by doRequest when GitHub rejects the token itself
+// (401 Unauthorized) — as opposed to a 403 which can mean rate-limited or
+// forbidden-but-authenticated. Callers use errors.As to distinguish a dead/
+// revoked token from other failures.
+type AuthError struct {
+	Message string
+}
+
+func (e *AuthError) Error() string {
+	return fmt.Sprintf("API error (status %d): %s", http.StatusUnauthorized, e.Message)
+}
+
+// parseRetryAfterHeader reads Retry-After and X-RateLimit-Reset headers and
+// returns the delay duration. Returns 0 when neither header is present.
+func parseRetryAfterHeader(h http.Header) time.Duration {
+	if v := h.Get("Retry-After"); v != "" {
+		if secs, err := strconv.Atoi(v); err == nil && secs > 0 {
+			return time.Duration(secs) * time.Second
+		}
+	}
+	if v := h.Get("X-RateLimit-Reset"); v != "" {
+		if unix, err := strconv.ParseInt(v, 10, 64); err == nil {
+			if d := time.Until(time.Unix(unix, 0)); d > 0 {
+				return d
+			}
+		}
+	}
+	return 0
+}

sdk/integrations/github/errors_test.go

@@ -0,0 +1,187 @@
+package github
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"testing"
+	"time"
+
+	"github.com/qf-studio/studio-sdk/sdk/testutil"
+)
+
+func newErrClient(t *testing.T, status int, body string, headers map[string]string) *Client {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		for k, v := range headers {
+			w.Header().Set(k, v)
+		}
+		w.WriteHeader(status)
+		_, _ = w.Write([]byte(body))
+	}))
+	t.Cleanup(srv.Close)
+	return NewClientWithBaseURL(testutil.FakeGitHubToken, srv.URL)
+}
+
+func TestDoRequest_429_ReturnsTypedRateLimitError(t *testing.T) {
+	c := newErrClient(t, http.StatusTooManyRequests, `{"message":"API rate limit exceeded"}`,
+		map[string]string{"Retry-After": "42"})
+
+	_, err := c.GetIssue(context.Background(), "o", "r", 1)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	var rlErr *RateLimitError
+	if !errors.As(err, &rlErr) {
+		t.Fatalf("error is %T, want *RateLimitError (errors.As must match for autopilot handling)", err)
+	}
+	if rlErr.StatusCode != http.StatusTooManyRequests {
+		t.Errorf("StatusCode = %d, want 429", rlErr.StatusCode)
+	}
+	if rlErr.RetryAfter != 42*time.Second {
+		t.Errorf("RetryAfter = %v, want 42s", rlErr.RetryAfter)
+	}
+}
+
+func TestDoRequest_403RateLimit_ReturnsTypedRateLimitError(t *testing.T) {
+	tests := []struct {
+		name    string
+		body    string
+		headers map[string]string
+	}{
+		{
+			name:    "remaining zero header",
+			body:    `{"message":"forbidden"}`,
+			headers: map[string]string{"X-RateLimit-Remaining": "0", "X-RateLimit-Reset": strconv.FormatInt(time.Now().Add(90*time.Second).Unix(), 10)},
+		},
+		{
+			name: "secondary rate limit message",
+			body: `{"message":"You have exceeded a secondary rate limit"}`,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			c := newErrClient(t, http.StatusForbidden, tt.body, tt.headers)
+			_, err := c.GetIssue(context.Background(), "o", "r", 1)
+			var rlErr *RateLimitError
+			if !errors.As(err, &rlErr) {
+				t.Fatalf("error is %T, want *RateLimitError", err)
+			}
+			if rlErr.StatusCode != http.StatusForbidden {
+				t.Errorf("StatusCode = %d, want 403", rlErr.StatusCode)
+			}
+		})
+	}
+}
+
+func TestDoRequest_403Plain_IsNotRateLimitError(t *testing.T) {
+	c := newErrClient(t, http.StatusForbidden, `{"message":"Resource not accessible by integration"}`, nil)
+	_, err := c.GetIssue(context.Background(), "o", "r", 1)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	var rlErr *RateLimitError
+	if errors.As(err, &rlErr) {
+		t.Error("plain 403 must NOT be classified as a rate limit")
+	}
+}
+
+func TestDoRequest_401_ReturnsTypedAuthError(t *testing.T) {
+	c := newErrClient(t, http.StatusUnauthorized, `{"message":"Bad credentials"}`, nil)
+	_, err := c.GetIssue(context.Background(), "o", "r", 1)
+	var authErr *AuthError
+	if !errors.As(err, &authErr) {
+		t.Fatalf("error is %T, want *AuthError", err)
+	}
+}
+
+func TestIsRetryable_TypedErrors(t *testing.T) {
+	if !isRetryableError(&RateLimitError{StatusCode: 403, Message: "secondary rate limit"}) {
+		t.Error("403-classified RateLimitError must be retryable (string path would miss it)")
+	}
+	if isRetryableError(&AuthError{Message: "Bad credentials"}) {
+		t.Error("AuthError must not be retryable")
+	}
+}
+
+func TestExtractRetryAfter_TypedFastPath(t *testing.T) {
+	got := extractRetryAfter(&RateLimitError{StatusCode: 429, RetryAfter: 17 * time.Second})
+	if got != 17*time.Second {
+		t.Errorf("extractRetryAfter = %v, want 17s", got)
+	}
+}
+
+func TestParseParentIssueNumber_Exported(t *testing.T) {
+	if n := ParseParentIssueNumber("Parent: #37\n\nBody"); n != 37 {
+		t.Errorf("ParseParentIssueNumber = %d, want 37", n)
+	}
+	if n := ParseParentIssueNumber("Parent: GH-42"); n != 42 {
+		t.Errorf("ParseParentIssueNumber = %d, want 42", n)
+	}
+	if n := ParseParentIssueNumber("no parent here"); n != 0 {
+		t.Errorf("ParseParentIssueNumber = %d, want 0", n)
+	}
+}
+
+func TestFailedRetryStateLabels(t *testing.T) {
+	want := []string{"pilot-failed-retry-1", "pilot-failed-retry-2", "pilot-failed-retry-exhausted"}
+	if len(FailedRetryStateLabels) != len(want) {
+		t.Fatalf("FailedRetryStateLabels = %v", FailedRetryStateLabels)
+	}
+	for i, w := range want {
+		if FailedRetryStateLabels[i] != w {
+			t.Errorf("FailedRetryStateLabels[%d] = %q, want %q", i, FailedRetryStateLabels[i], w)
+		}
+	}
+	if LabelPilot != "pilot" {
+		t.Errorf("LabelPilot = %q, want pilot", LabelPilot)
+	}
+}
+
+func TestGetOpenSubIssueNumbers(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path == "/graphql" {
+			_, _ = w.Write([]byte(`{"data":{"node":{"subIssues":{"totalCount":3,"nodes":[
+				{"number":11,"state":"OPEN"},{"number":12,"state":"CLOSED"},{"number":13,"state":"OPEN"}]}}}}`))
+			return
+		}
+		_, _ = w.Write([]byte(`{"node_id":"I_parent","number":10}`))
+	}))
+	defer srv.Close()
+
+	c := NewClientWithBaseURL(testutil.FakeGitHubToken, srv.URL)
+	numbers, hasLinks, err := c.GetOpenSubIssueNumbers(context.Background(), "o", "r", 10)
+	if err != nil {
+		t.Fatalf("GetOpenSubIssueNumbers: %v", err)
+	}
+	if !hasLinks {
+		t.Error("hasNativeLinks = false, want true (totalCount 3)")
+	}
+	if len(numbers) != 2 || numbers[0] != 11 || numbers[1] != 13 {
+		t.Errorf("numbers = %v, want [11 13]", numbers)
+	}
+}
+
+func TestGetOpenSubIssueNumbers_NoNativeLinks(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if r.URL.Path == "/graphql" {
+			_, _ = w.Write([]byte(`{"data":{"node":{"subIssues":{"totalCount":0,"nodes":[]}}}}`))
+			return
+		}
+		_, _ = w.Write([]byte(`{"node_id":"I_parent","number":10}`))
+	}))
+	defer srv.Close()
+
+	c := NewClientWithBaseURL(testutil.FakeGitHubToken, srv.URL)
+	numbers, hasLinks, err := c.GetOpenSubIssueNumbers(context.Background(), "o", "r", 10)
+	if err != nil {
+		t.Fatalf("GetOpenSubIssueNumbers: %v", err)
+	}
+	if hasLinks || numbers != nil {
+		t.Errorf("got (%v, %v), want (nil, false)", numbers, hasLinks)
+	}
+}

sdk/integrations/github/poller.go

@@ -1603,6 +1603,13 @@ func ParseDependencies(body string) []int {
 // parentRefRegex extracts parent issue references from issue body.
 var parentRefRegex = regexp.MustCompile(`(?m)^Parent:\s*(?:GH-|#)(\d+)`)
 
+// ParseParentIssueNumber extracts the parent issue number ("Parent: #N" /
+// "Parent: GH-N") from an issue body. Returns 0 if no parent reference is
+// found. Exported for hosts that apply parent-based gating outside the poller.
+func ParseParentIssueNumber(body string) int {
+	return parseParentIssueNumber(body)
+}
+
 // parseParentIssueNumber extracts the parent issue number from an issue body.
 // Returns 0 if no parent reference is found.
 func parseParentIssueNumber(body string) int {

sdk/integrations/github/retry.go

@@ -2,6 +2,7 @@ package github
 
 import (
 	"context"
+	"errors"
 	"regexp"
 	"strconv"
 	"strings"
@@ -97,6 +98,18 @@ func isRetryableError(err error) bool {
 		return false
 	}
 
+	// Typed fast path: doRequest classifies 429s and 403-rate-limits as
+	// *RateLimitError (including 403s whose Error() string would not match
+	// the status-code list below).
+	var rlErr *RateLimitError
+	if errors.As(err, &rlErr) {
+		return true
+	}
+	var authErr *AuthError
+	if errors.As(err, &authErr) {
+		return false // dead token — retrying cannot help
+	}
+
 	errStr := err.Error()
 
 	// Check for retryable HTTP status codes
@@ -149,6 +162,13 @@ func extractRetryAfter(err error) time.Duration {
 		return 0
 	}
 
+	// Typed fast path: doRequest parses Retry-After/X-RateLimit-Reset headers
+	// into RateLimitError.RetryAfter — no string parsing needed.
+	var rlErr *RateLimitError
+	if errors.As(err, &rlErr) && rlErr.RetryAfter > 0 {
+		return rlErr.RetryAfter
+	}
+
 	errStr := err.Error()
 
 	// GitHub API sometimes includes retry-after info in error response