add timeout exit code for wait polling (PRINFRA-125) (#46)

## Description
This follows the merged --wait polling framework with a clearer timeout contract for agents and scripts. Poll timeouts now return exit code 4 only after resource creation is confirmed, emit partial resource data on stdout when available, keep cancel distinct from timeout, and surface command-specific follow-up hints such as manual get commands for the created resource.

## Testing
- go test ./internal/client/... -run "ExecuteAndPoll|ExtractJSONPath" -count=1
- go test ./cmd/heygen/... -run "VideoCreate_Wait|VideoAgentCreate_Wait|GeneratedRoot_RootHelp" -count=1
- go test ./...

Author: somanshreddy

AGENTS.md

@@ -24,7 +24,7 @@ internal/auth/     CredentialResolver interface + implementations
 internal/client/   HTTP client, Executor
 internal/command/  Spec, Invocation, Groups, Column types
 internal/config/   config.Provider interface + implementations
-internal/errors/   CLIError, APIError, exit codes (0/1/2/3)
+internal/errors/   CLIError, APIError, exit codes (0/1/2/3/4)
 internal/output/   Formatter interface (JSONFormatter, HumanFormatter)
 internal/paths/    Config/credential file path resolution
 gen/               GENERATED — do not hand-edit
@@ -79,4 +79,4 @@ Data(v json.RawMessage, dataField string, columns []command.Column) error
 - All automated tests use `httptest.Server`. No real API calls in tests or CI.
 - Command tests: use `runCommand()` in `cmd/heygen/testutil_test.go`. It creates a fresh Cobra tree, captures stdout/stderr/exit code, and renders errors through the formatter (same path as `main()`).
 - Use `t.Setenv()` for env vars (auto-restored).
-- Assert on exit codes (0/1/2/3) **and** stderr envelope shape, not just error presence.
+- Assert on exit codes (0/1/2/3/4) **and** stderr envelope shape, not just error presence.

CLAUDE.md

@@ -22,7 +22,7 @@ internal/auth/     CredentialResolver interface + implementations
 internal/client/   HTTP client, Executor
 internal/command/  Spec, Invocation, Groups, Column types
 internal/config/   config.Provider interface + implementations
-internal/errors/   CLIError, APIError, exit codes (0/1/2/3)
+internal/errors/   CLIError, APIError, exit codes (0/1/2/3/4)
 internal/output/   Formatter interface (JSONFormatter, HumanFormatter)
 internal/paths/    Config/credential file path resolution
 gen/               GENERATED — do not hand-edit
@@ -77,4 +77,4 @@ Data(v json.RawMessage, dataField string, columns []command.Column) error
 - All automated tests use `httptest.Server`. No real API calls in tests or CI.
 - Command tests: use `runCommand()` in `cmd/heygen/testutil_test.go`. It creates a fresh Cobra tree, captures stdout/stderr/exit code, and renders errors through the formatter (same path as `main()`).
 - Use `t.Setenv()` for env vars (auto-restored).
-- Assert on exit codes (0/1/2/3) **and** stderr envelope shape, not just error presence.
+- Assert on exit codes (0/1/2/3/4) **and** stderr envelope shape, not just error presence.

cmd/heygen/builder.go

@@ -78,6 +78,24 @@ func buildCobraCommand(spec *command.Spec, ctx *cmdContext) *cobra.Command {
 
 					result, err := ctx.client.ExecuteAndPoll(cmd.Context(), &pollSpec, inv, opts)
 					if err != nil {
+						var timeoutErr *client.ErrPollTimeout
+						if errors.As(err, &timeoutErr) {
+							if timeoutErr.Data != nil {
+								if fmtErr := ctx.formatter.Data(timeoutErr.Data, "data", nil); fmtErr != nil {
+									return fmtErr
+								}
+							}
+							hint := "Re-run the corresponding get command to check the current status manually"
+							if pc.HintCommand != "" {
+								hint = fmt.Sprintf("heygen %s %s", pc.HintCommand, timeoutErr.ResourceID)
+							}
+							return &clierrors.CLIError{
+								Code:     "timeout",
+								Message:  fmt.Sprintf("polling timed out after %s", timeout),
+								Hint:     hint,
+								ExitCode: clierrors.ExitTimeout,
+							}
+						}
 						var failErr *client.ErrPollFailed
 						if errors.As(err, &failErr) {
 							// Output the failure response (contains error details),

cmd/heygen/builder_test.go

@@ -43,6 +43,16 @@ var videoCreateWaitSpec = &command.Spec{
 	Examples:     []string{"heygen video create --wait"},
 }
 
+var videoAgentWaitSpec = &command.Spec{
+	Group:        "video-agent",
+	Name:         "create",
+	Summary:      "Create video with Video Agent",
+	Endpoint:     "/v3/video-agents",
+	Method:       "POST",
+	BodyEncoding: "json",
+	Examples:     []string{"heygen video-agent create --wait"},
+}
+
 func TestGenBuilder_VideoList_Success(t *testing.T) {
 	srv := setupTestServer(t, map[string]testHandler{
 		"GET /v3/videos": {
@@ -203,12 +213,112 @@ func TestGenBuilder_VideoCreate_Wait_Timeout(t *testing.T) {
 
 	res := runGenCommand(t, srv.URL, "test-key", videoCreateWaitSpec, "create", "--wait", "--timeout", "20ms")
 
-	if res.ExitCode != 1 {
-		t.Fatalf("ExitCode = %d, want 1\nstderr: %s", res.ExitCode, res.Stderr)
+	if res.ExitCode != clierrors.ExitTimeout {
+		t.Fatalf("ExitCode = %d, want %d\nstderr: %s", res.ExitCode, clierrors.ExitTimeout, res.Stderr)
 	}
-	if !strings.Contains(res.Stderr, "polling timed out before the operation completed") {
+	if !strings.Contains(res.Stderr, "polling timed out after 20ms") {
 		t.Fatalf("stderr = %s, want timeout message", res.Stderr)
 	}
+	if !strings.Contains(res.Stderr, "heygen video get vid_123") {
+		t.Fatalf("stderr = %s, want follow-up hint", res.Stderr)
+	}
+
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(res.Stdout), &parsed); err != nil {
+		t.Fatalf("stdout should contain partial response: %v\nstdout: %s", err, res.Stdout)
+	}
+	data := parsed["data"].(map[string]any)
+	if data["status"] != "processing" {
+		t.Fatalf("status = %v, want processing", data["status"])
+	}
+}
+
+func TestGenBuilder_VideoCreate_Wait_TimeoutBeforeFirstPoll(t *testing.T) {
+	srv := setupTestServer(t, map[string]testHandler{
+		"POST /v3/videos": {
+			StatusCode: 200,
+			Body:       `{"data":{"video_id":"vid_123"}}`,
+		},
+		"GET /v3/videos/vid_123": {
+			StatusCode: 200,
+			ValidateRequest: func(t *testing.T, r *http.Request) {
+				t.Helper()
+				<-r.Context().Done()
+			},
+			Body: `{"data":{"video_id":"vid_123","status":"processing"}}`,
+		},
+	})
+	defer srv.Close()
+
+	res := runGenCommand(t, srv.URL, "test-key", videoCreateWaitSpec, "create", "--wait", "--timeout", "20ms")
+
+	if res.ExitCode != clierrors.ExitTimeout {
+		t.Fatalf("ExitCode = %d, want %d\nstderr: %s", res.ExitCode, clierrors.ExitTimeout, res.Stderr)
+	}
+	if strings.TrimSpace(res.Stdout) != "" {
+		t.Fatalf("stdout = %q, want empty when no status response was received", res.Stdout)
+	}
+}
+
+func TestGenBuilder_VideoCreate_Wait_Timeout_Human(t *testing.T) {
+	srv := setupTestServer(t, map[string]testHandler{
+		"POST /v3/videos": {
+			StatusCode: 200,
+			Body:       `{"data":{"video_id":"vid_123"}}`,
+		},
+		"GET /v3/videos/vid_123": {
+			StatusCode: 200,
+			Body:       `{"data":{"video_id":"vid_123","status":"processing","created_at":1774712936}}`,
+		},
+	})
+	defer srv.Close()
+
+	res := runGenCommand(t, srv.URL, "test-key", videoCreateWaitSpec, "create", "--wait", "--timeout", "20ms", "--human")
+
+	if res.ExitCode != clierrors.ExitTimeout {
+		t.Fatalf("ExitCode = %d, want %d\nstderr: %s", res.ExitCode, clierrors.ExitTimeout, res.Stderr)
+	}
+	if !strings.Contains(res.Stderr, "Polling: status=processing") {
+		t.Fatalf("stderr = %s, want progress output", res.Stderr)
+	}
+	if !strings.Contains(res.Stderr, "Error: polling timed out after 20ms") {
+		t.Fatalf("stderr = %s, want human timeout error", res.Stderr)
+	}
+	if !strings.Contains(res.Stderr, "Hint: heygen video get vid_123") {
+		t.Fatalf("stderr = %s, want human hint", res.Stderr)
+	}
+	if !strings.Contains(res.Stdout, "Video Id") && !strings.Contains(res.Stdout, "Video ID") && !strings.Contains(res.Stdout, "video_id") {
+		t.Fatalf("stdout = %s, want rendered partial result", res.Stdout)
+	}
+	if !strings.Contains(res.Stdout, "processing") {
+		t.Fatalf("stdout = %s, want processing status", res.Stdout)
+	}
+}
+
+func TestGenBuilder_VideoAgentCreate_Wait_Timeout_UsesVideoGetHint(t *testing.T) {
+	srv := setupTestServer(t, map[string]testHandler{
+		"POST /v3/video-agents": {
+			StatusCode: 200,
+			Body:       `{"data":{"session_id":"sess_123","video_id":"vid_123"}}`,
+		},
+		"GET /v3/videos/vid_123": {
+			StatusCode: 200,
+			Body:       `{"data":{"video_id":"vid_123","status":"processing"}}`,
+		},
+	})
+	defer srv.Close()
+
+	res := runGenCommand(t, srv.URL, "test-key", videoAgentWaitSpec, "create", "--wait", "--timeout", "20ms")
+
+	if res.ExitCode != clierrors.ExitTimeout {
+		t.Fatalf("ExitCode = %d, want %d\nstderr: %s", res.ExitCode, clierrors.ExitTimeout, res.Stderr)
+	}
+	if !strings.Contains(res.Stderr, "heygen video get vid_123") {
+		t.Fatalf("stderr = %s, want video get hint", res.Stderr)
+	}
+	if strings.Contains(res.Stderr, "video-agent get") {
+		t.Fatalf("stderr = %s, should not suggest video-agent get", res.Stderr)
+	}
 }
 
 func TestGenBuilder_VideoCreate_NoWait(t *testing.T) {

cmd/heygen/generated_root_test.go

@@ -210,6 +210,20 @@ func TestGeneratedRoot_VideoHelp_RemainsFlat(t *testing.T) {
 	}
 }
 
+func TestGeneratedRoot_RootHelp_ListsTimeoutExitCode(t *testing.T) {
+	srv := setupTestServer(t, map[string]testHandler{})
+	defer srv.Close()
+
+	res := runCommand(t, srv.URL, "", "--help")
+
+	if res.ExitCode != 0 {
+		t.Fatalf("ExitCode = %d, want 0\nstderr: %s", res.ExitCode, res.Stderr)
+	}
+	if !strings.Contains(res.Stdout, "4   Timeout (resource created but operation not yet complete)") {
+		t.Fatalf("root help missing exit code 4\nstdout: %s", res.Stdout)
+	}
+}
+
 func TestGeneratedRoot_UnknownFlagStillUsageError(t *testing.T) {
 	srv := setupTestServer(t, map[string]testHandler{})
 	defer srv.Close()

cmd/heygen/poll_configs.go

@@ -11,6 +11,7 @@ var pollConfigs = map[string]*command.PollConfig{
 		TerminalOK:     []string{"completed"},
 		TerminalFail:   []string{"failed"},
 		IDField:        "data.video_id",
+		HintCommand:    "video get",
 	},
 	// The create response returns video_translation_ids (plural, always a list
 	// even for single-language requests). We extract the first element with ".0".
@@ -21,6 +22,7 @@ var pollConfigs = map[string]*command.PollConfig{
 		TerminalOK:     []string{"completed"},
 		TerminalFail:   []string{"failed"},
 		IDField:        "data.video_translation_ids.0",
+		HintCommand:    "video-translate get",
 	},
 	// video-agent returns session_id + video_id. We poll the video status.
 	// video_id can be null in future multi-turn flows — extractJSONPath
@@ -31,5 +33,6 @@ var pollConfigs = map[string]*command.PollConfig{
 		TerminalOK:     []string{"completed"},
 		TerminalFail:   []string{"failed"},
 		IDField:        "data.video_id",
+		HintCommand:    "video get",
 	},
 }

cmd/heygen/root.go

@@ -26,7 +26,14 @@ Environment Variables:
   HEYGEN_API_KEY     API key for authentication (overrides stored credentials)
   HEYGEN_OUTPUT      Output format: json, human (default: json)
 
-Use "heygen config list" to see all configuration settings and their sources.`,
+Use "heygen config list" to see all configuration settings and their sources.
+
+Exit Codes:
+  0   Success
+  1   General error (API error, network failure)
+  2   Usage error (invalid flags, missing arguments)
+  3   Authentication error (missing or invalid API key)
+  4   Timeout (resource created but operation not yet complete)`,
 		Version:       version,
 		SilenceUsage:  true, // we handle usage errors ourselves
 		SilenceErrors: true, // we handle error output ourselves

internal/client/executor.go

@@ -47,6 +47,17 @@ func (e *ErrPollFailed) Error() string {
 	return fmt.Sprintf("operation reached terminal failure state: %s", e.Status)
 }
 
+// ErrPollTimeout is returned when polling times out after the resource has
+// been created but before a terminal status is reached.
+type ErrPollTimeout struct {
+	Data       json.RawMessage
+	ResourceID string
+}
+
+func (e *ErrPollTimeout) Error() string {
+	return fmt.Sprintf("polling timed out (resource %s still in progress)", e.ResourceID)
+}
+
 // ExecuteAndPoll executes a create request, then polls a status endpoint until
 // the resource reaches a terminal state or the context is canceled.
 func (c *Client) ExecuteAndPoll(
@@ -65,7 +76,7 @@ func (c *Client) ExecuteAndPoll(
 
 	createResp, err := c.executeWithContext(pollCtx, spec, inv)
 	if err != nil {
-		return nil, translatePollContextError(pollCtx, err)
+		return nil, translateCreateContextError(pollCtx, err)
 	}
 
 	resourceID, err := extractJSONPath(createResp, spec.PollConfig.IDField)
@@ -102,16 +113,21 @@ func (c *Client) ExecuteAndPoll(
 		MaxDelay:  opts.MaxDelay,
 	}
 	start := time.Now()
+	var lastStatusResp json.RawMessage
 
 	for attempt := 0; ; attempt++ {
 		if err := pollCtx.Err(); err != nil {
-			return nil, newPollContextError(err)
+			return nil, classifyPollContextError(err, resourceID, lastStatusResp)
 		}
 
 		statusResp, err := c.executeWithContext(pollCtx, statusSpec, statusInv)
 		if err != nil {
-			return nil, translatePollContextError(pollCtx, err)
+			if ctxErr := pollCtx.Err(); ctxErr != nil {
+				return nil, classifyPollContextError(ctxErr, resourceID, lastStatusResp)
+			}
+			return nil, err
 		}
+		lastStatusResp = statusResp
 
 		status, err := extractJSONPath(statusResp, spec.PollConfig.StatusField)
 		if err != nil {
@@ -133,7 +149,10 @@ func (c *Client) ExecuteAndPoll(
 
 		delay := backoffDelay(attempt, pollBackoff)
 		if err := waitForRetry(pollCtx, delay); err != nil {
-			return nil, newPollContextError(err)
+			if ctxErr := pollCtx.Err(); ctxErr != nil {
+				return nil, classifyPollContextError(ctxErr, resourceID, lastStatusResp)
+			}
+			return nil, err
 		}
 	}
 }
@@ -402,35 +421,32 @@ func extractJSONPath(raw json.RawMessage, path string) (string, error) {
 	return value, nil
 }
 
-// translatePollContextError converts context deadline/cancellation errors into
-// user-friendly CLIErrors. This includes unwrapping context errors that were
-// stringified into CLIError.Message by executeWithContext — CLIError doesn't
-// preserve the error chain, so string matching is the fallback. If the message
-// format in executeWithContext changes, this degrades to returning the original
-// error (generic network failure), which is safe but less user-friendly.
-func translatePollContextError(ctx context.Context, err error) error {
+// translateCreateContextError converts timeout/cancel errors before a resource
+// ID is known into user-friendly CLIErrors. At this stage the client cannot
+// confirm whether creation succeeded, so exit code stays general.
+func translateCreateContextError(ctx context.Context, err error) error {
 	if ctxErr := ctx.Err(); ctxErr != nil {
-		return newPollContextError(ctxErr)
+		return newCreateContextError(ctxErr)
 	}
 	if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
-		return newPollContextError(err)
+		return newCreateContextError(err)
 	}
 
 	var cliErr *clierrors.CLIError
 	if errors.As(err, &cliErr) && cliErr.Code == "network_error" {
 		msg := strings.ToLower(cliErr.Message)
 		switch {
 		case strings.Contains(msg, "context deadline exceeded"):
-			return newPollContextError(context.DeadlineExceeded)
+			return newCreateContextError(context.DeadlineExceeded)
 		case strings.Contains(msg, "context canceled"), strings.Contains(msg, "context cancelled"):
-			return newPollContextError(context.Canceled)
+			return newCreateContextError(context.Canceled)
 		}
 	}
 
 	return err
 }
 
-func newPollContextError(err error) error {
+func newCreateContextError(err error) error {
 	switch {
 	case errors.Is(err, context.DeadlineExceeded):
 		return &clierrors.CLIError{
@@ -451,6 +467,24 @@ func newPollContextError(err error) error {
 	}
 }
 
+func classifyPollContextError(err error, resourceID string, lastResp json.RawMessage) error {
+	if err == nil {
+		return clierrors.New("unexpected nil context error during polling")
+	}
+	if errors.Is(err, context.DeadlineExceeded) {
+		return &ErrPollTimeout{
+			Data:       lastResp,
+			ResourceID: resourceID,
+		}
+	}
+	return &clierrors.CLIError{
+		Code:     "canceled",
+		Message:  "polling was canceled before the operation completed",
+		Hint:     "Re-run the corresponding get command to check the current status manually",
+		ExitCode: clierrors.ExitGeneral,
+	}
+}
+
 // parseErrorResponse parses an API error response into a CLIError.
 func parseErrorResponse(statusCode int, body []byte, requestID string) *clierrors.CLIError {
 	var envelope struct {